Merge remote-tracking branch 'origin/main' into claude/issue-64-9QSsY

# Conflicts:
#	app/packages/web/e2e/specs/auth-gate.spec.ts

Author: claude

CLAUDE.md

@@ -165,16 +165,24 @@ The test suite has two complementary tiers:
 
 | Tier | Command | What runs | When to add specs |
 |------|---------|-----------|-------------------|
-| **Unit / integration** | `npm run app:test` | Vitest — server-side logic, hooks, helpers. No browser, no real network. AWS SDK mocked via `aws-sdk-client-mock`. | Pure logic, hook behaviour, server controllers. |
+| **Unit / integration** | `npm run app:test` | Vitest. Server-side logic, hooks, helpers run under the `node` environment; React component specs in `@gsd/web` run under `jsdom` via `environmentMatchGlobs`. No real network — AWS SDK mocked via `aws-sdk-client-mock`; the `@gsd/web` API client is stubbed via `vi.mock`. | Pure logic, hook behaviour, server controllers, **per-component React behaviour** (rendering, callbacks, internal state transitions). |
 | **E2E (tier 1 — #74)** | `npm run app:test:e2e` | Playwright against `vite build` + `vite preview`. Nest server never runs; every `/api/*` call is stubbed at the network layer via `page.route()`. | User-visible flows: routing, auth gate, button interactions, status-badge rendering, optimistic updates. |
 
 A planned **tier 2** (#75) will add full-stack specs (real Nest + mocked AWS SDK) for scenarios that require real HTTP contract validation between the client and server. Until that lands, all browser-facing specs belong in tier 1.
 
+**React component unit tests (`@gsd/web`):**
+- Use **Vitest + jsdom + `@testing-library/react` + `@testing-library/user-event`**. `@testing-library/jest-dom` matchers (`toBeInTheDocument`, `toHaveTextContent`, etc.) are auto-loaded via `app/vitest.setup.ts`.
+- `app/vitest.config.ts` flips to the `jsdom` environment for everything under `packages/web/**` so server tests stay on Node. The setup file also wires `afterEach(cleanup)` because we run with `globals: false`, which disables RTL's normal auto-cleanup.
+- Tests live **next to the component** (`Foo.tsx` → `Foo.test.tsx`), not in a separate `__tests__` directory. Mock the API client and any module-level singletons via `vi.mock`. Use `vi.stubGlobal('EventSource', …)` for SSE-driven components (jsdom doesn't ship one).
+- Cover: visible rendering for each `state` branch, every callback prop firing with the right argument, internal state transitions (open/close, pause/resume), and any non-trivial pure helper. Don't reach for snapshots — they break on every Tailwind tweak. Don't repeat assertions already covered by the e2e tier (full SSE streaming flow, real network, full routing).
+
 **Playwright conventions:**
 - Specs live under `app/packages/web/e2e/specs/`.
 - Shared stub helpers and fixtures are in `app/packages/web/e2e/fixtures/`.
-- Import `{ test, expect, stubApis }` from `../fixtures/index.js` for authenticated specs; use `@playwright/test` directly for auth-gate specs.
-- Use the `authedPage` fixture (token pre-seeded in localStorage) for any spec that is not testing the auth flow itself.
+- **Page objects** for each route live in `app/packages/web/e2e/pages/` (`DashboardPage`, `CostsPage`, `LogsPage`, etc.). Specs **must** reach for elements through a page-object method (`logs.pauseButton()`, `dashboard.gameCardHeading('minecraft')`) rather than calling `page.getByX(...)` directly. The page object centralises locator drift, gives spec files a vocabulary that reads like the feature it's testing, and is the only place locator strategy (role + accessible name vs. text vs. test-id) gets decided. Add a new page object whenever a spec wants a locator that isn't already wrapped.
+- Each page object receives a `Page` in its constructor and exposes `goto()` plus typed `Locator`-returning methods. Encapsulate multi-step flows (`dashboard.filter(query)`, `logs.toggleLevel('ERROR')`) so individual specs stay one-liners.
+- Import `{ test, expect, stubApis }` plus the page-object fixture you need (`logs`, `dashboard`, `costs`, `layout`, `authGate`) from `../fixtures/index.js` for authenticated specs; use `@playwright/test` directly for auth-gate specs.
+- Use the `authedPage` fixture (token pre-seeded in localStorage) only when a spec needs raw `Page` access (e.g. to call `stubApis` or `addInitScript`); otherwise prefer the higher-level page-object fixtures.
 - Stubs must cover every `/api/*` endpoint the page hits, or the catch-all returns 404 and the test will surface the missing stub quickly.
 
 ## Git & Branch Workflow
@@ -187,6 +195,22 @@ Use `.worktrees/<branch-name>` for feature work (the directory is gitignored). C
 git worktree add .worktrees/<branch> -b <branch>
 ```
 
+## Claude Code Plugins
+
+This repo expects the **`issue-flow`** plugin (from `CoderCoco/claude-plugin-marketplace`) to drive the issue → PR loop. Two skills, used in order:
+
+- **`work-on`** — start work on a GitHub issue. Creates the `claude/issue-<N>-<slug>` branch, scaffolds a worktree, and pulls the issue checklist into the session as the source of truth for what "done" means.
+- **`open-pr`** — finish the loop. Verifies the issue checklist is actually complete, picks up the repo's PR conventions (the rules in the next section), opens the PR with the right `Closes #N` keyword, and moves the project card to "In Review".
+
+Install once:
+
+```
+/plugin marketplace add CoderCoco/claude-plugin-marketplace
+/plugin install issue-flow@claude-plugin-marketplace
+```
+
+If the plugin isn't loaded in the current environment, fetch the skill body from the marketplace repo and follow it manually — don't fall back to ad-hoc PR creation, because the skills enforce checklist-completeness and the closing keyword that this repo's `/pr` command takes for granted.
+
 ## PR Conventions
 
 - **Always use `/pr` to create pull requests.** The `.claude/commands/pr.md` skill validates the title format before calling the API. Never call `mcp__github__create_pull_request` directly without running this check first.

app/packages/web/e2e/fixtures/game-data.ts

@@ -1,4 +1,11 @@
-import type { GameStatus, CostEstimates, EnvInfo, WatchdogConfig } from '../../src/api.js';
+import type {
+  GameStatus,
+  CostEstimates,
+  EnvInfo,
+  WatchdogConfig,
+  ActualCosts,
+  DiscordConfigRedacted,
+} from '@/api.js';
 
 /** Stub response for `GET /api/env`. */
 export const ENV_DATA: EnvInfo = {
@@ -48,3 +55,115 @@ export const COST_DATA: CostEstimates = {
   },
   totalPerHourIfAllOn: 0.08,
 };
+
+/** Multi-game estimates fixture for sort / filter specs on the Costs page. */
+export const MULTI_GAME_COST_DATA: CostEstimates = {
+  games: {
+    minecraft: {
+      vcpu: 1,
+      memoryGb: 2,
+      costPerHour: 0.08,
+      costPerDay24h: 1.92,
+      costPerMonth4hpd: 9.6,
+    },
+    valheim: {
+      vcpu: 2,
+      memoryGb: 4,
+      costPerHour: 0.16,
+      costPerDay24h: 3.84,
+      costPerMonth4hpd: 19.2,
+    },
+    palworld: {
+      vcpu: 4,
+      memoryGb: 8,
+      costPerHour: 0.32,
+      costPerDay24h: 7.68,
+      costPerMonth4hpd: 38.4,
+    },
+  },
+  totalPerHourIfAllOn: 0.56,
+};
+
+/** Stub response for `GET /api/costs/actual` — 7 days of synthetic spend used by the KPI sparklines. */
+export const ACTUAL_COSTS: ActualCosts = {
+  daily: [
+    { date: '2026-04-26', cost: 0.42 },
+    { date: '2026-04-27', cost: 0.31 },
+    { date: '2026-04-28', cost: 0.55 },
+    { date: '2026-04-29', cost: 0.18 },
+    { date: '2026-04-30', cost: 0.27 },
+    { date: '2026-05-01', cost: 0.40 },
+    { date: '2026-05-02', cost: 0.35 },
+  ],
+  total: 2.48,
+  currency: 'USD',
+  days: 7,
+};
+
+/**
+ * Build a deterministic `ActualCosts` payload with `days` daily entries.
+ * The first half of the window costs $0.50/day and the second half costs
+ * $1.00/day, so the Costs page renders a non-zero delta-vs-prior pill when
+ * the page fetches both `days=7` (current) and `days=14` (prior) windows
+ * from the same stub.
+ */
+export function makeActualCosts(days: number): ActualCosts {
+  const daily = Array.from({ length: days }, (_, i) => ({
+    date: `2026-04-${String((i % 30) + 1).padStart(2, '0')}`,
+    cost: i < days / 2 ? 0.5 : 1.0,
+  }));
+  const total = daily.reduce((sum, d) => sum + d.cost, 0);
+  return { daily, total: Math.round(total * 100) / 100, currency: 'USD', days };
+}
+
+/** A valid Discord snowflake (17–20 digits) for use in test inputs. */
+export const VALID_GUILD_ID = '123456789012345678';
+/** A second valid snowflake — useful for multi-guild specs. */
+export const VALID_GUILD_ID_2 = '987654321098765432';
+/** A valid user-shaped snowflake for admin/permission specs. */
+export const VALID_USER_ID = '111122223333444455';
+
+/**
+ * First-run Discord config — no guilds, no admins, no secrets configured.
+ * Triggers the `/discord` setup-wizard render path.
+ */
+export const FIRST_RUN_DISCORD_CONFIG: DiscordConfigRedacted = {
+  clientId: '',
+  allowedGuilds: [],
+  admins: { userIds: [], roleIds: [] },
+  gamePermissions: {},
+  baseAllowedGuilds: [],
+  baseAdmins: { userIds: [], roleIds: [] },
+  botTokenSet: false,
+  publicKeySet: false,
+  interactionsEndpointUrl: null,
+};
+
+/**
+ * Fully-configured Discord config — bot token + public key set, one allowlisted
+ * guild, one admin user. Used to exercise the post-setup tabs.
+ */
+export const CONFIGURED_DISCORD_CONFIG: DiscordConfigRedacted = {
+  clientId: '111111111111111111',
+  allowedGuilds: [VALID_GUILD_ID],
+  admins: { userIds: [VALID_USER_ID], roleIds: [] },
+  gamePermissions: {},
+  baseAllowedGuilds: [],
+  baseAdmins: { userIds: [], roleIds: [] },
+  botTokenSet: true,
+  publicKeySet: true,
+  interactionsEndpointUrl: 'https://abc123.lambda-url.us-east-1.on.aws/',
+};
+
+/**
+ * A handful of CloudWatch lines with mixed log levels — used by the LogsPage
+ * specs to exercise level-badge detection, search highlighting, and the
+ * Levels filter.
+ */
+export const SAMPLE_LOG_LINES: string[] = [
+  '2026-05-03T12:00:00Z INFO Server started on port 25565',
+  '2026-05-03T12:00:01Z DEBUG Loaded world "world" in 1.2s',
+  '2026-05-03T12:00:02Z WARN Deprecated config option "max-tick-time"',
+  '2026-05-03T12:00:03Z ERROR Connection refused from 10.0.0.5',
+  '2026-05-03T12:00:04Z Player joined the game',
+];

app/packages/web/e2e/fixtures/index.ts

@@ -1,22 +1,90 @@
 import { test as base, type Page } from '@playwright/test';
-import type { GameStatus, CostEstimates, EnvInfo, ActionResult, WatchdogConfig } from '../../src/api.js';
-import { ENV_DATA, STOPPED_GAME, COST_DATA, WATCHDOG_CONFIG } from './game-data.js';
+import type {
+  GameStatus,
+  CostEstimates,
+  EnvInfo,
+  ActionResult,
+  WatchdogConfig,
+  ActualCosts,
+  DiscordConfigRedacted,
+} from '@/api.js';
+import {
+  ENV_DATA,
+  STOPPED_GAME,
+  COST_DATA,
+  WATCHDOG_CONFIG,
+  CONFIGURED_DISCORD_CONFIG,
+  makeActualCosts,
+} from './game-data.js';
+import { AppLayout, AuthGatePage, DashboardPage, CostsPage, LogsPage } from '../pages/index.js';
 
-export type { GameStatus, CostEstimates, EnvInfo, WatchdogConfig };
-export { ENV_DATA, STOPPED_GAME, RUNNING_GAME, MULTI_GAME_STATUSES, COST_DATA, WATCHDOG_CONFIG } from './game-data.js';
+export type {
+  GameStatus,
+  CostEstimates,
+  EnvInfo,
+  WatchdogConfig,
+  ActualCosts,
+  DiscordConfigRedacted,
+};
+export {
+  ENV_DATA,
+  STOPPED_GAME,
+  RUNNING_GAME,
+  MULTI_GAME_STATUSES,
+  COST_DATA,
+  MULTI_GAME_COST_DATA,
+  WATCHDOG_CONFIG,
+  ACTUAL_COSTS,
+  makeActualCosts,
+  FIRST_RUN_DISCORD_CONFIG,
+  CONFIGURED_DISCORD_CONFIG,
+  VALID_GUILD_ID,
+  VALID_GUILD_ID_2,
+  VALID_USER_ID,
+  SAMPLE_LOG_LINES,
+} from './game-data.js';
+export { AppLayout, AuthGatePage, DashboardPage, CostsPage, LogsPage } from '../pages/index.js';
 
 /** Per-spec overrides for the default `/api/*` stubs registered by `stubApis`. */
 export interface StubOptions {
   /** Game statuses returned by `GET /api/status`. Defaults to `[STOPPED_GAME]`. */
   statuses?: GameStatus[];
   /** Cost estimates returned by `GET /api/costs/estimate`. */
   costs?: CostEstimates;
+  /**
+   * Either a fixed `ActualCosts` payload returned for every `GET /api/costs/actual`
+   * call, or a builder receiving the `days` query param so a spec can return
+   * different totals per window (the Costs page calls both `days` and `days*2`).
+   * Defaults to `makeActualCosts(days)` so the prior-period delta is non-zero.
+   */
+  actualCosts?: ActualCosts | ((days: number) => ActualCosts);
   /** Env info returned by `GET /api/env`. */
   env?: EnvInfo;
   /** Watchdog config returned by `GET /api/config`. */
   config?: WatchdogConfig;
   /** Override for `POST /api/start/:game` response. */
   startResult?: ActionResult;
+  /**
+   * Discord config returned by `GET /api/discord/config`. Defaults to
+   * `CONFIGURED_DISCORD_CONFIG` so non-Discord specs hitting `/discord` (e.g.
+   * sidebar nav) don't trip the catch-all 404 handler. Pass
+   * `FIRST_RUN_DISCORD_CONFIG` to exercise the setup wizard.
+   */
+  discord?: DiscordConfigRedacted;
+  /**
+   * Game names returned by `GET /api/games` (used by the Logs page).
+   * Defaults to the names derived from `statuses`. Override when the Logs
+   * page should expose games that aren't part of `statuses`.
+   */
+  games?: string[];
+  /**
+   * Initial log lines returned by `GET /api/logs/:game` (used by the Logs
+   * page). Maps game name → seeded lines. Games not present in the map
+   * receive an empty buffer. The SSE stream at `/api/logs/:game/stream` is
+   * always aborted so EventSource gives up immediately and tests don't hang
+   * on a never-ending response.
+   */
+  logLines?: Record<string, string[]>;
 }
 
 /**
@@ -35,6 +103,15 @@ export async function stubApis(page: Page, opts: StubOptions = {}): Promise<void
   const env = opts.env ?? ENV_DATA;
   const config = opts.config ?? WATCHDOG_CONFIG;
   const startResult: ActionResult = opts.startResult ?? { success: true, message: 'Started' };
+  const discord = opts.discord ?? CONFIGURED_DISCORD_CONFIG;
+  const games = opts.games ?? statuses.map((s) => s.game);
+  const logLines = opts.logLines ?? {};
+  const actualCostsFn: (days: number) => ActualCosts =
+    typeof opts.actualCosts === 'function'
+      ? opts.actualCosts
+      : opts.actualCosts !== undefined
+        ? () => opts.actualCosts as ActualCosts
+        : (days) => makeActualCosts(days);
 
   await page.route('**/api/**', (route) =>
     route.fulfill({ status: 404, json: { error: 'not stubbed' } })
@@ -50,8 +127,18 @@ export async function stubApis(page: Page, opts: StubOptions = {}): Promise<void
     return route.fulfill({ json: s });
   });
 
+  await page.route('**/api/games', (route) => route.fulfill({ json: { games } }));
+
   await page.route('**/api/costs/estimate', (route) => route.fulfill({ json: costs }));
 
+  // Trailing `*` matches the `?days=N` query string — Playwright globs are
+  // matched against the full URL, and `*` (= `[^/]*`) covers query payloads
+  // that never contain a slash.
+  await page.route('**/api/costs/actual*', (route) => {
+    const days = parseInt(new URL(route.request().url()).searchParams.get('days') ?? '7', 10);
+    return route.fulfill({ json: actualCostsFn(days) });
+  });
+
   await page.route('**/api/config', (route) => {
     if (route.request().method() === 'POST') {
       return route.fulfill({ json: { success: true, config } });
@@ -64,14 +151,61 @@ export async function stubApis(page: Page, opts: StubOptions = {}): Promise<void
   await page.route('**/api/stop/*', (route) =>
     route.fulfill({ json: { success: true, message: 'Stopped' } as ActionResult })
   );
+
+  // Discord — read endpoint plus permissive write endpoints. Specs that need
+  // to assert request bodies should override these with their own page.route().
+  await page.route('**/api/discord/config', (route) => {
+    if (route.request().method() === 'PUT') {
+      return route.fulfill({ json: { success: true, config: discord } });
+    }
+    return route.fulfill({ json: discord });
+  });
+  await page.route('**/api/discord/guilds', (route) =>
+    route.fulfill({ json: { success: true, guilds: discord.allowedGuilds } }),
+  );
+  await page.route('**/api/discord/guilds/*', (route) =>
+    route.fulfill({ json: { success: true, guilds: discord.allowedGuilds } }),
+  );
+  await page.route('**/api/discord/guilds/*/register-commands', (route) =>
+    route.fulfill({ json: { success: true, message: 'Registered' } }),
+  );
+  await page.route('**/api/discord/admins', (route) =>
+    route.fulfill({ json: { success: true, admins: discord.admins } }),
+  );
+  await page.route('**/api/discord/permissions/*', (route) =>
+    route.fulfill({ json: { success: true, permissions: discord.gamePermissions } }),
+  );
+
+  // Logs page — the SSE stream is aborted so EventSource gives up immediately.
+  // Specs that need to drive the stream can override this route after stubApis().
+  // The `/stream*` glob is registered AFTER `/api/logs/*` so it wins for SSE
+  // URLs (Playwright matches routes in reverse registration order).
+  await page.route('**/api/logs/*', (route) => {
+    const url = new URL(route.request().url());
+    const game = url.pathname.split('/').pop()!;
+    return route.fulfill({ json: { game, lines: logLines[game] ?? [] } });
+  });
+  await page.route('**/api/logs/*/stream*', (route) => route.abort());
 }
 
 type E2EFixtures = {
   /**
    * A page with `apiToken` pre-seeded in localStorage so every navigation
-   * starts authenticated. Use this in all specs except auth-gate tests.
+   * starts authenticated. Use this in specs that need raw page access (e.g.
+   * to call `stubApis` or `addInitScript`); prefer `dashboard` / `costs` /
+   * `layout` for higher-level interactions.
    */
   authedPage: Page;
+  /** Page object for the dashboard route — use in any authed-dashboard spec. */
+  dashboard: DashboardPage;
+  /** Page object for the `/costs` route — use in any authed-costs spec. */
+  costs: CostsPage;
+  /** Page object for the `/logs` route — use in any authed-logs spec. */
+  logs: LogsPage;
+  /** Page object for the persistent nav shell (sidebar + top bar). */
+  layout: AppLayout;
+  /** Page object for the API-token modal — use in auth-gate specs. */
+  authGate: AuthGatePage;
 };
 
 export const test = base.extend<E2EFixtures>({
@@ -81,6 +215,25 @@ export const test = base.extend<E2EFixtures>({
     });
     await use(page);
   },
+  // `dashboard` and `costs` depend on `authedPage` because every authed-route
+  // spec wants the token pre-seeded. `layout` and `authGate` depend on the raw
+  // `page` so auth-gate specs (which exercise the unauthenticated state) can
+  // use them without dragging the init script along.
+  dashboard: async ({ authedPage }, use) => {
+    await use(new DashboardPage(authedPage));
+  },
+  costs: async ({ authedPage }, use) => {
+    await use(new CostsPage(authedPage));
+  },
+  logs: async ({ authedPage }, use) => {
+    await use(new LogsPage(authedPage));
+  },
+  layout: async ({ page }, use) => {
+    await use(new AppLayout(page));
+  },
+  authGate: async ({ page }, use) => {
+    await use(new AuthGatePage(page));
+  },
 });
 
 export { expect } from '@playwright/test';