From 8604f678c18eb959557273f8c2244399f98c3f28 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Thu, 19 Nov 2026 01:47:41 +0300 Subject: [PATCH 1/6] feat(updates): GET /api/updates sends the running version to everyone (MC-68) Co-Authored-By: Claude Opus 5.5 --- backend/app/updates/router.py | 10 +++++----- backend/app/updates/schemas.py | 1 + backend/tests/updates/test_router.py | 19 ++++++++++++++++--- 3 files changed, 22 insertions(+), 8 deletions(-) diff --git a/backend/app/updates/router.py b/backend/app/updates/router.py index ba881993..fbcd243e 100644 --- a/backend/app/updates/router.py +++ b/backend/app/updates/router.py @@ -13,16 +13,16 @@ @router.get("/api/updates") async def get_updates(user: AuthedUser, db: DbSession) -> UpdatesOut: - """The latest releases, as the update check last found them. The server's own update is for admins only: - they are the ones who can install it.""" + """The running version, for everyone signed in, and the latest releases as the update check last found them. + The server's own update is for admins only: they are the ones who can install it.""" + current = get_settings().app_version org = await db.get(OrgSettings, ORG_SETTINGS_ID) if org is None: - return UpdatesOut() - current = get_settings().app_version + return UpdatesOut(app_version=current) app = None if user.role == Role.admin and org.latest_app_url and is_newer(org.latest_app_version, current): app = AppUpdate(current=current, latest=org.latest_app_version, url=org.latest_app_url) runner = None if org.latest_runner_version and org.latest_runner_url: runner = RunnerRelease(latest=org.latest_runner_version, url=org.latest_runner_url) - return UpdatesOut(app=app, runner=runner) + return UpdatesOut(app_version=current, app=app, runner=runner) diff --git a/backend/app/updates/schemas.py b/backend/app/updates/schemas.py index de982b35..67401598 100644 --- a/backend/app/updates/schemas.py +++ b/backend/app/updates/schemas.py @@ -13,5 +13,6 @@ class RunnerRelease(BaseModel): class UpdatesOut(BaseModel): + app_version: str # the version this server runs ("dev" from source); for everyone signed in app: AppUpdate | None = None # admins only, and only when the server is older than the latest release runner: RunnerRelease | None = None # each agent's runner version is compared with it by the frontend diff --git a/backend/tests/updates/test_router.py b/backend/tests/updates/test_router.py index 38e78367..8123e458 100644 --- a/backend/tests/updates/test_router.py +++ b/backend/tests/updates/test_router.py @@ -31,13 +31,13 @@ async def _updates(client, db, monkeypatch, *, role: Role, app_version: str) -> async def test_an_admin_is_told_of_a_newer_server(client, db, monkeypatch, stored): body = await _updates(client, db, monkeypatch, role=Role.admin, app_version="0.1.0") - assert body == {"app": {"current": "0.1.0", "latest": "0.2.0", "url": APP_URL}, + assert body == {"app_version": "0.1.0", "app": {"current": "0.1.0", "latest": "0.2.0", "url": APP_URL}, "runner": {"latest": "0.1.1", "url": RUNNER_URL}} async def test_a_member_is_not_told_of_the_server(client, db, monkeypatch, stored): body = await _updates(client, db, monkeypatch, role=Role.member, app_version="0.1.0") - assert body == {"app": None, "runner": {"latest": "0.1.1", "url": RUNNER_URL}} + assert body == {"app_version": "0.1.0", "app": None, "runner": {"latest": "0.1.1", "url": RUNNER_URL}} @pytest.mark.parametrize("app_version", ["dev", "0.2.0", "0.3.0"]) @@ -49,7 +49,20 @@ async def test_no_pill_from_source_or_when_up_to_date(client, db, monkeypatch, s async def test_nothing_known_yet(client, db, monkeypatch): db.add(OrgSettings(id=ORG_SETTINGS_ID, name="Acme")) await db.commit() - assert await _updates(client, db, monkeypatch, role=Role.admin, app_version="0.1.0") == {"app": None, "runner": None} + assert await _updates(client, db, monkeypatch, role=Role.admin, app_version="0.1.0") == { + "app_version": "0.1.0", "app": None, "runner": None} + + +@pytest.mark.parametrize("role", [Role.admin, Role.member]) +@pytest.mark.parametrize("app_version", ["dev", "0.2.0", "0.24.0-dev+abc"]) +async def test_everyone_gets_the_running_version(client, db, monkeypatch, stored, role, app_version): + body = await _updates(client, db, monkeypatch, role=role, app_version=app_version) + assert body["app_version"] == app_version + + +async def test_the_version_comes_before_the_organization_is_set_up(client, db, monkeypatch): + assert await _updates(client, db, monkeypatch, role=Role.member, app_version="0.1.0") == { + "app_version": "0.1.0", "app": None, "runner": None} async def test_an_agent_carries_its_runners_version(client, db, monkeypatch): From 25e76f54c3e0a32498b1b4a8d05a14c008874ef4 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Thu, 19 Nov 2026 01:51:55 +0300 Subject: [PATCH 2/6] feat(versions): label and release link for the running version (MC-68) Co-Authored-By: Claude Opus 5.5 --- frontend/src/lib/__tests__/versions.test.ts | 17 ++++++++++++++++- frontend/src/lib/versions.ts | 15 +++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/frontend/src/lib/__tests__/versions.test.ts b/frontend/src/lib/__tests__/versions.test.ts index 64d0ec93..035f93bd 100644 --- a/frontend/src/lib/__tests__/versions.test.ts +++ b/frontend/src/lib/__tests__/versions.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from "vitest"; -import { isNewer, parseVersion } from "@/lib/versions"; +import { isNewer, parseVersion, releaseUrl, versionLabel } from "@/lib/versions"; describe("versions", () => { it("reads only release versions", () => { @@ -21,4 +21,19 @@ describe("versions", () => { expect(isNewer("0.2.0", "0.1.0-dev+abc")).toBe(false); expect(isNewer(null, "0.1.0")).toBe(false); }); + + it("labels the running version, never with a doubled v", () => { + expect(versionLabel("0.23.1")).toBe("v0.23.1"); + expect(versionLabel("v0.23.1")).toBe("v0.23.1"); + expect(versionLabel(" dev ")).toBe("dev"); + expect(versionLabel("0.24.0-dev+abc")).toBe("0.24.0-dev+abc"); + for (const v of ["", null, undefined]) expect(versionLabel(v)).toBe(""); + }); + + it("links only a release to its notes", () => { + const url = "https://github.com/mmhy2003/MegooColab/releases/tag/v0.23.1"; + expect(releaseUrl("0.23.1")).toBe(url); + expect(releaseUrl("v0.23.1")).toBe(url); + for (const v of ["dev", "0.24.0-dev+abc", "", null]) expect(releaseUrl(v)).toBeNull(); + }); }); diff --git a/frontend/src/lib/versions.ts b/frontend/src/lib/versions.ts index c8d47f15..e4cf0676 100644 --- a/frontend/src/lib/versions.ts +++ b/frontend/src/lib/versions.ts @@ -14,3 +14,18 @@ export function isNewer(latest?: string | null, current?: string | null): boolea for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i]; return false; } + +const RELEASES = "https://github.com/mmhy2003/MegooColab/releases/tag/"; + +/** The running version as shown: a release as "v0.23.1" (never "vv0.23.1"); anything else (dev, 0.24.0-dev+abc) + * as it is, trimmed. */ +export function versionLabel(v?: string | null): string { + const r = parseVersion(v); + return r ? `v${r.join(".")}` : (v ?? "").trim(); +} + +/** The release's notes on GitHub; null for a build from source, which has no release page. */ +export function releaseUrl(v?: string | null): string | null { + const r = parseVersion(v); + return r ? `${RELEASES}v${r.join(".")}` : null; +} From 7ee804aa41743de41f8572bbe6e7fa2d6b9c67e8 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Thu, 19 Nov 2026 01:55:32 +0300 Subject: [PATCH 3/6] feat(shell): AppVersion shows the server's version, linked to its release notes (MC-68) Co-Authored-By: Claude Opus 5.5 --- frontend/src/components/shell/AppVersion.tsx | 39 ++++++++++++ .../shell/__tests__/AppVersion.test.tsx | 62 +++++++++++++++++++ frontend/src/lib/api-types.ts | 6 +- 3 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 frontend/src/components/shell/AppVersion.tsx create mode 100644 frontend/src/components/shell/__tests__/AppVersion.test.tsx diff --git a/frontend/src/components/shell/AppVersion.tsx b/frontend/src/components/shell/AppVersion.tsx new file mode 100644 index 00000000..b30dcc28 --- /dev/null +++ b/frontend/src/components/shell/AppVersion.tsx @@ -0,0 +1,39 @@ +"use client"; + +import { Hint } from "@/components/ui/Hint"; +import { useUpdates } from "@/lib/updates"; +import { releaseUrl, versionLabel } from "@/lib/versions"; + +const LOOK = "text-xs whitespace-nowrap text-muted-foreground tabular-nums no-underline"; + +/** The MegooColab version the server runs, for everyone signed in ("I'm on v0.23.1" in a bug report). A release + * links to its notes on GitHub; a build from source ("dev") has none, so it is plain text. Nothing while the version + * is not known (loading, a failed request, a server older than this page). */ +export function AppVersion({ className = "" }: { className?: string }) { + const version = useUpdates().data?.app_version; + const label = versionLabel(version); + if (!label) return null; + const url = releaseUrl(version); + if (!url) { + return ( + + MegooColab + {label} + + ); + } + const number = label.slice(1); + return ( + + + {label} + + + ); +} diff --git a/frontend/src/components/shell/__tests__/AppVersion.test.tsx b/frontend/src/components/shell/__tests__/AppVersion.test.tsx new file mode 100644 index 00000000..ec84c18f --- /dev/null +++ b/frontend/src/components/shell/__tests__/AppVersion.test.tsx @@ -0,0 +1,62 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { cleanup, render, screen } from "@testing-library/react"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { AppVersion } from "@/components/shell/AppVersion"; + +function renderVersion(updates: object, { status = 200, className }: { status?: number; className?: string } = {}) { + vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify(updates), { status }))); + const client = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + return render( + + + , + ); +} + +afterEach(() => { + cleanup(); + vi.unstubAllGlobals(); +}); + +describe("AppVersion", () => { + it("shows a release as v0.23.1, linked to its notes in a new tab", async () => { + renderVersion({ app_version: "0.23.1", app: null, runner: null }); + const link = await screen.findByRole("link", { name: "MegooColab 0.23.1, release notes (opens in a new tab)" }); + expect(link).toHaveAttribute("href", "https://github.com/mmhy2003/MegooColab/releases/tag/v0.23.1"); + expect(link).toHaveAttribute("target", "_blank"); + expect(link).toHaveAttribute("rel", "noreferrer"); + expect(link).toHaveTextContent("v0.23.1"); + }); + + it("does not double the v of a version that has one", async () => { + renderVersion({ app_version: "v0.23.1", app: null, runner: null }); + const link = await screen.findByRole("link"); + expect(link.textContent).toBe("v0.23.1"); + }); + + it("shows a build from source as plain text, without a link", async () => { + renderVersion({ app_version: "dev", app: null, runner: null }); + const el = (await screen.findByText("dev")).closest("[title]") as HTMLElement; + expect(screen.queryByRole("link")).toBeNull(); + expect(el).toHaveAttribute("title", "dev"); + expect(el.textContent).toBe("MegooColab dev"); + }); + + it("shows nothing when the server does not say its version", async () => { + const { container } = renderVersion({ app: null, runner: null }); + await new Promise((r) => setTimeout(r, 20)); + expect(container).toBeEmptyDOMElement(); + }); + + it("shows nothing when the request fails", async () => { + const { container } = renderVersion({ detail: "boom" }, { status: 500 }); + await new Promise((r) => setTimeout(r, 20)); + expect(container).toBeEmptyDOMElement(); + }); + + it("puts the caller's className on the link", async () => { + renderVersion({ app_version: "0.23.1", app: null, runner: null }, { className: "ml-auto" }); + expect(await screen.findByRole("link")).toHaveClass("ml-auto"); + }); +}); diff --git a/frontend/src/lib/api-types.ts b/frontend/src/lib/api-types.ts index 47c3ce5a..41c1c648 100644 --- a/frontend/src/lib/api-types.ts +++ b/frontend/src/lib/api-types.ts @@ -3867,8 +3867,8 @@ export interface paths { }; /** * Get Updates - * @description The latest releases, as the update check last found them. The server's own update is for admins only: - * they are the ones who can install it. + * @description The running version, for everyone signed in, and the latest releases as the update check last found them. + * The server's own update is for admins only: they are the ones who can install it. */ get: operations["get_updates_api_updates_get"]; put?: never; @@ -8496,6 +8496,8 @@ export interface components { }; /** UpdatesOut */ UpdatesOut: { + /** App Version */ + app_version: string; app?: components["schemas"]["AppUpdate"] | null; runner?: components["schemas"]["RunnerRelease"] | null; }; From 5eb51ad40e9d6d31d0e4455061215101f3905030 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Thu, 19 Nov 2026 01:58:35 +0300 Subject: [PATCH 4/6] feat(shell): the version sits at the foot of the desktop sidebar (MC-68) Co-Authored-By: Claude Opus 5.5 --- .../src/components/shell/DesktopSidebar.tsx | 28 +++++++----- .../shell/__tests__/DesktopSidebar.test.tsx | 44 ++++++++++++++++++- 2 files changed, 59 insertions(+), 13 deletions(-) diff --git a/frontend/src/components/shell/DesktopSidebar.tsx b/frontend/src/components/shell/DesktopSidebar.tsx index a75a9ea3..35348765 100644 --- a/frontend/src/components/shell/DesktopSidebar.tsx +++ b/frontend/src/components/shell/DesktopSidebar.tsx @@ -3,6 +3,7 @@ import { ChevronsLeft, ChevronsRight } from "lucide-react"; import { useState } from "react"; +import { AppVersion } from "@/components/shell/AppVersion"; import { LABEL_HIDDEN, Sidebar } from "@/components/shell/Sidebar"; import { Hint } from "@/components/ui/Hint"; import type { User } from "@/lib/types"; @@ -55,17 +56,22 @@ export function DesktopSidebar({ user }: { user: User }) {
- - - + {/* the Collapse button keeps its width; the version sits at the right of the same row and, like every label, + hides on the closed rail (tabbing onto its link opens the rail) */} +
+ + + + +
); diff --git a/frontend/src/components/shell/__tests__/DesktopSidebar.test.tsx b/frontend/src/components/shell/__tests__/DesktopSidebar.test.tsx index afd886ba..c575802b 100644 --- a/frontend/src/components/shell/__tests__/DesktopSidebar.test.tsx +++ b/frontend/src/components/shell/__tests__/DesktopSidebar.test.tsx @@ -4,6 +4,7 @@ import type { ReactNode } from "react"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { DesktopSidebar, SIDEBAR_KEY } from "@/components/shell/DesktopSidebar"; +import { LABEL_HIDDEN } from "@/components/shell/Sidebar"; import type { User } from "@/lib/types"; vi.mock("next/navigation", () => ({ usePathname: () => "/projects" })); @@ -14,7 +15,7 @@ function aside() { return screen.getByRole("complementary"); } -// the Dashboard entry asks for its badge count +// the Dashboard entry asks for its badge count; the footer asks for the running version function wrap(ui: ReactNode) { const client = new QueryClient({ defaultOptions: { queries: { retry: false } } }); return render({ui}); @@ -22,7 +23,20 @@ function wrap(ui: ReactNode) { beforeEach(() => { localStorage.clear(); - vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ needs_you: 0 }), { status: 200 }))); + vi.stubGlobal( + "fetch", + vi.fn( + async (url: RequestInfo | URL) => + new Response( + JSON.stringify( + String(url).includes("/api/updates") + ? { app_version: "0.23.1", app: null, runner: null } + : { needs_you: 0 }, + ), + { status: 200 }, + ), + ), + ); }); afterEach(() => { cleanup(); @@ -68,4 +82,30 @@ describe("DesktopSidebar", () => { getItem.mockRestore(); setItem.mockRestore(); }); + + it("shows the version at the foot, after the Collapse button", async () => { + wrap(); + const v = await screen.findByRole("link", { name: /MegooColab 0\.23\.1/ }); + expect(aside()).toContainElement(v); + expect(v).toHaveTextContent("v0.23.1"); + const collapse = screen.getByRole("button", { name: "Collapse sidebar" }); + expect(collapse.compareDocumentPosition(v) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy(); + expect(v.className).toContain("ml-auto"); + expect(v.className).not.toContain("opacity-0"); + }); + + it("hides the version on the closed rail, like the labels", async () => { + localStorage.setItem(SIDEBAR_KEY, "collapsed"); + wrap(); + const v = await screen.findByRole("link", { name: /MegooColab 0\.23\.1/ }); + expect(LABEL_HIDDEN).toContain("opacity-0"); + expect(LABEL_HIDDEN).toContain("group-hover/side:opacity-100"); + expect(v.className).toContain(LABEL_HIDDEN); + }); + + it("a click on the version does not fold the sidebar", async () => { + wrap(); + fireEvent.click(await screen.findByRole("link", { name: /MegooColab 0\.23\.1/ })); + expect(aside()).toHaveAttribute("data-collapsed", "false"); + }); }); From ab0b6b6920cebbe4693038ae4d40fc39978afd7f Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Thu, 19 Nov 2026 02:10:15 +0300 Subject: [PATCH 5/6] feat(shell): the phone menu shows the version too (MC-68) Co-Authored-By: Claude Opus 5.5 --- frontend/e2e/layout.spec.ts | 34 +++++++++++++++++++++++++++++++ frontend/src/app/(app)/layout.tsx | 11 ++++++++-- 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/frontend/e2e/layout.spec.ts b/frontend/e2e/layout.spec.ts index f9424786..0ed27e00 100644 --- a/frontend/e2e/layout.spec.ts +++ b/frontend/e2e/layout.spec.ts @@ -163,3 +163,37 @@ test("text is set in Geist, code and keys in Geist Mono, the wordmark in Orbitro expect(fonts.length).toBeGreaterThan(0); expect(fonts.every((n) => !n.includes("fonts.g"))).toBe(true); }); + +test("everyone signed in sees the server's version at the foot of the sidebar", async ({ page, browser }) => { + // the e2e stack is built from source, so the server runs "dev": plain text, no release link + await setupOrSignIn(page); + const web = { "X-Megoo-Client": "web" }; + const email = `vera-${Date.now()}@acme.io`; // any stack: fresh or not + const invite = await page.request.post("/api/admin/users/invite", { + data: { email, name: "Vera Version", role: "member" }, + headers: web, + }); + expect(invite.ok(), await invite.text()).toBeTruthy(); + const token = (await invite.json()).invite_url.split("/invite/")[1]; + const ctx = await browser.newContext({ baseURL: process.env.E2E_BASE_URL ?? "http://localhost:8080" }); + try { + const accepted = await ctx.request.post("/api/auth/accept-invite", { + data: { token, password: "vera-password-123" }, + headers: web, + }); + expect(accepted.ok(), await accepted.text()).toBeTruthy(); + const member = await ctx.newPage(); + await member.setViewportSize({ width: 1280, height: 800 }); + await member.goto("/projects"); + const aside = member.locator("aside").first(); + await expect(aside.getByText("MegooColab dev", { exact: true })).toBeVisible(); + await expect(aside.getByRole("link", { name: /MegooColab/ })).toHaveCount(0); + + await member.setViewportSize({ width: 375, height: 700 }); + await member.getByRole("button", { name: "Open menu" }).click(); + const menu = member.getByRole("dialog", { name: "Menu" }); + await expect(menu.getByText("MegooColab dev", { exact: true })).toBeInViewport(); + } finally { + await ctx.close(); + } +}); diff --git a/frontend/src/app/(app)/layout.tsx b/frontend/src/app/(app)/layout.tsx index 4e1b8f8c..3fc5fb28 100644 --- a/frontend/src/app/(app)/layout.tsx +++ b/frontend/src/app/(app)/layout.tsx @@ -4,6 +4,7 @@ import { Suspense, useState } from "react"; import { NavRecorder } from "@/components/nav/NavRecorder"; import { TabBadge } from "@/components/notifications/TabBadge"; +import { AppVersion } from "@/components/shell/AppVersion"; import { DesktopSidebar } from "@/components/shell/DesktopSidebar"; import { Header } from "@/components/shell/Header"; import { Sidebar } from "@/components/shell/Sidebar"; @@ -32,8 +33,14 @@ export default function AppLayout({ children }: { children: React.ReactNode }) { {menuOpen && (
)} From ef732db32eb8a3317484ce03e37f6936348862d8 Mon Sep 17 00:00:00 2001 From: "Mohamed H. Youssef" Date: Thu, 19 Nov 2026 02:11:52 +0300 Subject: [PATCH 6/6] docs: MC-68 design and plan --- docs/superpowers/plans/MC-68-plan.md | 259 +++++++++++++++++++++++++ docs/superpowers/specs/MC-68-design.md | 79 ++++++++ 2 files changed, 338 insertions(+) create mode 100644 docs/superpowers/plans/MC-68-plan.md create mode 100644 docs/superpowers/specs/MC-68-design.md diff --git a/docs/superpowers/plans/MC-68-plan.md b/docs/superpowers/plans/MC-68-plan.md new file mode 100644 index 00000000..4ed9bca2 --- /dev/null +++ b/docs/superpowers/plans/MC-68-plan.md @@ -0,0 +1,259 @@ +# MC-68 plan: show the current version in the sidebar footer + +**Goal:** everyone who is signed in sees the server's MegooColab version ("v0.23.1") at the foot of the sidebar. A release's version links to its notes on GitHub. A build from source shows a plain `dev`. + +**Architecture:** `GET /api/updates` gets one new field, `app_version`, for every signed-in user. The frontend already loads this endpoint through `useUpdates()` and refreshes it every 15 minutes. Two pure helpers in `lib/versions.ts` turn the version into a label and a release URL. A new `AppVersion` component draws it on the Collapse row of the desktop sidebar and on a last row of the phone menu. + +## File map + +| File | Change | +|---|---| +| `backend/app/updates/schemas.py` | `UpdatesOut.app_version: str` (required) | +| `backend/app/updates/router.py` | `get_updates` sets `app_version` on both returns; docstring updated | +| `backend/tests/updates/test_router.py` | exact bodies gain `app_version`; new tests for everyone, `dev`, and no organization | +| `frontend/src/lib/versions.ts` | `versionLabel`, `releaseUrl` | +| `frontend/src/lib/__tests__/versions.test.ts` | tests for the two helpers | +| `frontend/src/lib/api-types.ts` | regenerated (`npm run gen:api`) | +| `frontend/src/components/shell/AppVersion.tsx` | new: the version as a link or as text | +| `frontend/src/components/shell/__tests__/AppVersion.test.tsx` | new | +| `frontend/src/components/shell/DesktopSidebar.tsx` | the Collapse button and `AppVersion` share one row | +| `frontend/src/components/shell/__tests__/DesktopSidebar.test.tsx` | footer tests; the fetch mock answers `/api/updates` | +| `frontend/src/app/(app)/layout.tsx` | the phone menu's aside becomes a column with a version row | +| `frontend/e2e/layout.spec.ts` | a member sees `dev` on the desktop and in the phone menu | + +## Code referred to by the steps + +### A. `frontend/src/lib/versions.ts` (append below `isNewer`) + +```ts +const RELEASES = "https://github.com/mmhy2003/MegooColab/releases/tag/"; + +/** The running version as shown: a release as "v0.23.1" (never "vv0.23.1"); anything else (dev, 0.24.0-dev+abc) + * as it is, trimmed. */ +export function versionLabel(v?: string | null): string { + const r = parseVersion(v); + return r ? `v${r.join(".")}` : (v ?? "").trim(); +} + +/** The release's notes on GitHub; null for a build from source, which has no release page. */ +export function releaseUrl(v?: string | null): string | null { + const r = parseVersion(v); + return r ? `${RELEASES}v${r.join(".")}` : null; +} +``` + +### B. `frontend/src/components/shell/AppVersion.tsx` + +```tsx +"use client"; + +import { Hint } from "@/components/ui/Hint"; +import { useUpdates } from "@/lib/updates"; +import { releaseUrl, versionLabel } from "@/lib/versions"; + +const LOOK = "text-xs whitespace-nowrap text-muted-foreground tabular-nums no-underline"; + +/** The MegooColab version the server runs, for everyone signed in ("I'm on v0.23.1" in a bug report). A release + * links to its notes on GitHub; a build from source ("dev") has none, so it is plain text. Nothing while the version + * is not known (loading, a failed request, a server older than this page). */ +export function AppVersion({ className = "" }: { className?: string }) { + const version = useUpdates().data?.app_version; + const label = versionLabel(version); + if (!label) return null; + const url = releaseUrl(version); + if (!url) { + return ( + + MegooColab + {label} + + ); + } + const number = label.slice(1); + return ( + + + {label} + + + ); +} +``` + +### C. DesktopSidebar footer (replaces the `…` block at the end of the inner div) + +```tsx +{/* the Collapse button keeps its width; the version sits at the right of the same row and, like every label, + hides on the closed rail (tabbing onto its link opens the rail) */} +
+ + + + +
+``` + +### D. Phone menu in `frontend/src/app/(app)/layout.tsx` + +```tsx + +``` + +### E. Playwright test, appended to `frontend/e2e/layout.spec.ts` + +```ts +test("everyone signed in sees the server's version at the foot of the sidebar", async ({ page, browser }) => { + // the e2e stack is built from source, so the server runs "dev": plain text, no release link + await setupOrSignIn(page); + const web = { "X-Megoo-Client": "web" }; + const email = `vera-${Date.now()}@acme.io`; // any stack: fresh or not + const invite = await page.request.post("/api/admin/users/invite", { + data: { email, name: "Vera Version", role: "member" }, + headers: web, + }); + expect(invite.ok(), await invite.text()).toBeTruthy(); + const token = (await invite.json()).invite_url.split("/invite/")[1]; + const ctx = await browser.newContext({ baseURL: process.env.E2E_BASE_URL ?? "http://localhost:8080" }); + try { + const accepted = await ctx.request.post("/api/auth/accept-invite", { + data: { token, password: "vera-password-123" }, + headers: web, + }); + expect(accepted.ok(), await accepted.text()).toBeTruthy(); + const member = await ctx.newPage(); + await member.setViewportSize({ width: 1280, height: 800 }); + await member.goto("/projects"); + const aside = member.locator("aside").first(); + await expect(aside.getByText("MegooColab dev", { exact: true })).toBeVisible(); + await expect(aside.getByRole("link", { name: /MegooColab/ })).toHaveCount(0); + + await member.setViewportSize({ width: 375, height: 700 }); + await member.getByRole("button", { name: "Open menu" }).click(); + const menu = member.getByRole("dialog", { name: "Menu" }); + await expect(menu.getByText("MegooColab dev", { exact: true })).toBeInViewport(); + } finally { + await ctx.close(); + } +}); +``` + +## Steps + +### 1. Backend: GET /api/updates sends the running version to everyone + +**Files:** `backend/app/updates/schemas.py`, `backend/app/updates/router.py`, `backend/tests/updates/test_router.py`. + +**Tests first** (`backend/tests/updates/test_router.py`): +- `test_an_admin_is_told_of_a_newer_server`: the expected body gains `"app_version": "0.1.0"`. +- `test_a_member_is_not_told_of_the_server`: expected `{"app_version": "0.1.0", "app": None, "runner": {...}}`. A member still gets `app: None`. +- `test_nothing_known_yet`: expected `{"app_version": "0.1.0", "app": None, "runner": None}`. +- New `test_everyone_gets_the_running_version`, parametrized over `role` in (`Role.admin`, `Role.member`) and `app_version` in (`"dev"`, `"0.2.0"`, `"0.24.0-dev+abc"`), with the `stored` fixture: `body["app_version"] == app_version`. +- New `test_the_version_comes_before_the_organization_is_set_up` (no `stored`, no `OrgSettings` row): `_updates(..., role=Role.member, app_version="0.1.0") == {"app_version": "0.1.0", "app": None, "runner": None}`. + +Run from `backend/`: `megoocolab-runner services run test -- uv run pytest tests/updates/test_router.py -q`. The tests fail because `app_version` is missing from the body. + +**Implement:** +- `schemas.py`: add `app_version: str # the version this server runs ("dev" from source); for everyone signed in` as the first field of `UpdatesOut`. It has no default, so the OpenAPI type is required. +- `router.py`: read `current = get_settings().app_version` before the `org is None` check, return `UpdatesOut(app_version=current)` there, and `UpdatesOut(app_version=current, app=app, runner=runner)` at the end. Docstring: "The running version, for everyone signed in, and the latest releases as the update check last found them. The server's own update is for admins only: they are the ones who can install it." Leave the admin rule for `app` as it is. + +Run again: everything passes. Then run `megoocolab-runner services run test -- uv run pytest tests/updates -q`. + +**Commit:** `feat(updates): GET /api/updates sends the running version to everyone (MC-68)` + +### 2. Frontend: versionLabel and releaseUrl helpers + +**Files:** `frontend/src/lib/versions.ts`, `frontend/src/lib/__tests__/versions.test.ts`. + +**Tests first:** add to the existing `describe("versions")` (and update the import): +- `versionLabel`: `"0.23.1"` gives `"v0.23.1"`, `"v0.23.1"` gives `"v0.23.1"`, `" dev "` gives `"dev"`, `"0.24.0-dev+abc"` gives `"0.24.0-dev+abc"`; `""`, `null` and `undefined` give `""`. +- `releaseUrl`: `"0.23.1"` and `"v0.23.1"` give `"https://github.com/mmhy2003/MegooColab/releases/tag/v0.23.1"`; `"dev"`, `"0.24.0-dev+abc"`, `""` and `null` give `null`. + +Run from `frontend/`: `npx vitest run src/lib/__tests__/versions.test.ts`. It fails because the exports do not exist. + +**Implement:** code block A in the plan, built on `parseVersion`. Run again: pass. Then `npx tsc --noEmit` and `npx eslint src/lib/versions.ts src/lib/__tests__/versions.test.ts`. + +**Commit:** `feat(versions): label and release link for the running version (MC-68)` + +### 3. Frontend: AppVersion component + +**Files:** `frontend/src/lib/api-types.ts` (regenerated), new `frontend/src/components/shell/AppVersion.tsx`, new `frontend/src/components/shell/__tests__/AppVersion.test.tsx`. + +**Regenerate types** from `frontend/`: `npm ci` if needed, then `npm run gen:api`. `UpdatesOut` now has `app_version: string`. Commit only the `api-types.ts` change; `openapi.json` is not tracked. + +**Tests first** (use the same pattern as `UpdatePill.test.tsx`: stub `fetch` with the body, `QueryClientProvider` with `retry: false`): +- "links a release to its notes": body `{app_version: "0.23.1", app: null, runner: null}`. `await screen.findByRole("link", { name: "MegooColab 0.23.1, release notes (opens in a new tab)" })` has `href` `https://github.com/mmhy2003/MegooColab/releases/tag/v0.23.1`, `target="_blank"`, `rel="noreferrer"`, and text `v0.23.1`. +- "does not double the v": `app_version: "v0.23.1"` shows the text `v0.23.1`. +- "shows a build from source as plain text": `app_version: "dev"`. `await screen.findByText("dev")`, and `screen.queryByRole("link")` is null. The element has `title="dev"` and its text is `MegooColab dev` (the visually hidden prefix). +- "draws nothing without a version": body `{app: null, runner: null}` (an old server). After `await new Promise((r) => setTimeout(r, 20))`, `container` is empty. A fetch that answers 500 also leaves it empty. +- "passes its className on": `className="ml-auto"` ends up on the link. + +Run `npx vitest run src/components/shell/__tests__/AppVersion.test.tsx`. It fails because the module is not found. + +**Implement:** code block B in the plan exactly. Run again: pass. Then `npx tsc --noEmit` and `npx eslint` on the two new files. + +**Commit:** `feat(shell): AppVersion shows the server's version, linked to its release notes (MC-68)` + +### 4. Desktop sidebar: the version on the Collapse row + +**Files:** `frontend/src/components/shell/DesktopSidebar.tsx`, `frontend/src/components/shell/__tests__/DesktopSidebar.test.tsx`. + +**Tests first:** +- Change the `beforeEach` fetch stub to answer by URL: `vi.fn(async (url: RequestInfo | URL) => new Response(JSON.stringify(String(url).includes("/api/updates") ? { app_version: "0.23.1", app: null, runner: null } : { needs_you: 0 }), { status: 200 }))`. +- "shows the version at the foot, after the Collapse button": `const v = await screen.findByRole("link", { name: /MegooColab 0\.23\.1/ })`. `v` is inside `aside()`, its text is `v0.23.1`, and `screen.getByRole("button", { name: "Collapse sidebar" }).compareDocumentPosition(v) & Node.DOCUMENT_POSITION_FOLLOWING` is truthy. `v.className` contains `ml-auto` and not `opacity-0`. +- "hides the version on the closed rail, like the labels": with `localStorage` set to collapsed, the link's className contains `opacity-0` and `group-hover/side:opacity-100`. +- "a click on the version does not fold the sidebar": `fireEvent.click(link)`; `data-collapsed` stays `"false"`. The Collapse button still toggles (the existing test covers that). + +Run `npx vitest run src/components/shell/__tests__/DesktopSidebar.test.tsx`. The new tests fail. + +**Implement:** replace the Hint/button block with code block C in the plan. The button loses `m-2` because the row carries it now. Import `AppVersion` from `@/components/shell/AppVersion`. Run again: everything passes. + +Then `npx tsc --noEmit`, `npx eslint` on both files, and `npm test` (the whole Vitest suite; the Dashboard 300 ms test is known to be flaky under load). + +**Commit:** `feat(shell): the version sits at the foot of the desktop sidebar (MC-68)` + +### 5. Phone menu row and browser test + +**Files:** `frontend/src/app/(app)/layout.tsx`, `frontend/e2e/layout.spec.ts`. + +**Browser test first:** append code block E in the plan to `frontend/e2e/layout.spec.ts`. It reuses the existing `setupOrSignIn` import. Run from `frontend/`: `megoocolab-runner services run e2e -- npx playwright test e2e/layout.spec.ts --reporter=line`. The new test fails at the phone-menu assertion; the desktop part already passes after step 4. + +**Implement:** in `layout.tsx`, replace the phone menu's `