Developer MessagesClaude MessagesShow Tool Use

jeff

Session 45: website improvements

I have been browsing around on the site and have some ideas for improvements:
Let's take these items one-by-one, only advancing to the next after we complete the current item.

In our last coding session we built the CodingSessionEditor but never got edit links to it working. Is there a way to directly navigate to the CodingSessionEditor with a url? The edit link urls to the CodingSessionEditor don't really make sense to me. Before spending time trying to get that working - I feel like the CodingSessionEditor could be purely client-side. I'd like to learn about our options related to purely client side functionality (pages/views). Would the implementation of the Logon page be considered purely client? It might be helpful to me if we organized the pages into folders like serverViews and 'clientViews`, what do you think about that?
Coding Session Content Pagination
2.1 The pagination doesn't work well on the first page of session content, it sometimes only shows one Message. I wonder if the size of the files is getting included in the page size calculation.
2.2 let's make a CODING_SESSION_PAGINATION=ON|OFF env variable so we can turn it on and off as needed
2.3 the Page navigation controls are way down at the bottom - we need to make it easier to go back and forth
2.4 after going to the next page, we are still scrolled all the way down at the bottom
2.5 there's no indication of what page you on until you get to the bottom
FileViewer - the font size is kind of large, let's make it smaller please.
Images uploaded to Claude Code during the coding sessions. Do the Claude Code transcripts capture images that the user gives to Claude Code? Are we capturing those images in the cwc-session-parser? I am not seeing those images in the ConversationViewer.
ConversationViewer and MessageBlocks - some message blocks are very large, especially from Claude when work is being done. It might be better to make the MessageBlock default to a collapsed state (shows 3-4 lines of text) initially.
ToolResultContent and ToolUseContent - it might make the Conversations more pleasant to read if we had a way to hide the ToolUse items. I'm thinking of a filters bar at the top of the CoversationViewer (fixed in place, doesn't scroll off) - we could have a variety of checkboxes including one for ToolUse which would default to unchecked.
can we tell what mode (planning or accept edits) Claude Code is in for each Message? It might be helpful to be able to identify those by a background color and it might be nice to be able to filter by that mode as well.
the formatting of the content in the ConversationViewer is not great, how are we handling markdown?

Claude

I'll start with item 1 - understanding the CodingSessionEditor navigation and client-side vs server-side views. Let me explore the current implementation to give you informed options.

Based on the exploration, I have a good understanding of the current architecture. Let me clarify a few things before designing a plan.

What I found:

CodingSessionEditor route exists: /project/:projectId/session/:sessionId/edit - so direct URL navigation should work
Edit links exist in the Project page's session table, but only visible when you're the project owner
The editor has a server-side loader (codingSessionEditorLoader.ts) that fetches session data via API calls
JWT handling is incomplete - there are TODO comments with empty string placeholders where JWT should come from auth context

The Logon page is a hybrid:

Client-side form rendering and state management
Server-side action() for processing the login POST request
It's NOT pre-rendered (not in prerender.ts)

Current SSG vs Client distinction:

Controlled by whether routes are in prerender.ts, not by folder structure
Routes outside SiteLayout (like CodingSessionEditor) are already excluded from pre-rendering

Claude is asking...

Edit IssueWhen you try to navigate to the edit URL, what happens? Does it show an error, blank page, or something else?

Error message- The page shows an error or fails to load

Blank page- The page loads but shows nothing

Data not loading- Page loads but session data is missing or wrong

Haven't tried yet- I want to understand the architecture first before testing

Client-side goalWhy do you want CodingSessionEditor to be purely client-side? What problem are you trying to solve?

Avoid SSG complexity- Don't want to deal with server-side data fetching during build

Auth handling- Easier to handle JWT/auth client-side after user is logged in

Faster development- Simpler to iterate on client-only code

All of the above- Multiple reasons

Folder orgFor folder organization (serverViews vs clientViews), what's driving this desire?

Clarity- Want to easily see which pages are SSG vs client-only

Different patterns- Client pages have different code patterns worth separating

Not important- This was just an idea, not a priority

Developer Response

Q: When you try to navigate to the edit URL, what happens? Does it show an error, blank page, or something else?

A: "in the `Current SSG vs Client distinction` section, in one statement you say that prerender.ts controls SSG, but in the other it sounds like SiteLayout plays some part in this. I would argue that `views/CodingSession/CodingSession.tsx` is `outside SiteLayout` but it is included it SSG."

Q: Why do you want CodingSessionEditor to be purely client-side? What problem are you trying to solve?

A: "All of the above"

Q: For folder organization (serverViews vs clientViews), what's driving this desire?

A: "Clarity"

You're absolutely right - I was imprecise. Let me clarify:

What actually controls SSG:

prerender.ts - explicitly lists which URLs get pre-rendered at build time
SiteLayout - just a layout wrapper (header/footer), has nothing to do with SSG

CodingSession IS pre-rendered (it's in prerender.ts) despite being outside SiteLayout - these are orthogonal concerns.

So the real distinction is:

Route	In prerender.ts?	Has Loader?	Result
CodingSession	Yes	Yes	SSG - loader runs at build time
CodingSessionEditor	No	Yes	Loader runs client-side on navigation
Logon	No	No (has action)	Pure client-side rendering

Let me explore the CodingSessionEditor's loader to understand how it currently handles authentication, then I'll design a plan for making it purely client-side.

Now I understand the full picture. Let me also check the Logon implementation to see the pattern for a client-only page:

Now I have a complete picture. Let me summarize the key insight and write the plan.

Key Insight - Why Server Loaders Can't Get JWT:

The current CodingSessionEditor has a loader that runs server-side (or at build time for SSG). The problem is:

JWT is stored client-side (localStorage via useAuth())
Server-side loaders run BEFORE the React component mounts
The loader has NO access to client-side auth context

That's why the loader works (fetching public data) but save/delete fail (can't get JWT).

The Solution - Purely Client-Side:

For authenticated pages like CodingSessionEditor:

Remove the server loader
Fetch data in useEffect after component mounts
Get JWT from useAuth() hook (available in component)
Handle loading/error states in the component

This is the same pattern as Logon (no loader, client-side state management).

Approach	Has Loader?	When Data Fetched	Auth Access
SSG	Yes	Build time	❌ No client state
Server-side	Yes	Request time	❌ No client state
Client-side	No	After mount (useEffect)	✅ Has auth context

I've drafted the plan. Before finalizing, let me confirm a few details:

Claude is asking...

Folder namesFor the folder names, which do you prefer?

ssg/ and client/- Short and descriptive (my suggestion)

serverViews/ and clientViews/- Your original suggestion

prerendered/ and dynamic/- Alternative naming based on build behavior

ScopeShould we do both parts (client-side conversion + folder reorganization) in this item, or just the client-side conversion first?

Both together- Convert to client-side AND reorganize folders

Client-side first- Just convert CodingSessionEditor, defer folder reorganization

Developer Response

Q: For the folder names, which do you prefer?

A: "the problem with my original suggestion and your suggestions is that they separate the views too much in my opinion. what if we create `server` and `client` subfolders within the `views` folder. I like `server` better than `ssg` because we also handle `ssr` (only for test right now, but who knows what the future holds)"

Q: Should we do both parts (client-side conversion + folder reorganization) in this item, or just the client-side conversion first?

A: "Both together"

Good clarifications. Let me update the plan with:

views/server/ and views/client/ subfolders
Using server instead of ssg (accommodates both SSG and SSR)
Doing both parts together

Let me verify the actual view folder structure to make sure the plan is accurate:

Good catch - I see CodingSessionPage.tsx is inside the CodingSession/ folder, not separate. Let me fix the plan:

Let me also check the prerender.ts to see if it needs path updates:

Good - prerender.ts generates URL paths, not file paths, so it won't need updating. Let me check if there are any cross-view imports that might need attention:

No cross-view imports - views are self-contained. The plan is complete. Let me read it to verify everything is coherent:

Let me fix one minor issue - prerender.ts doesn't need updating since it generates URL paths, not file paths:

The plan is complete. Here's a summary:

Plan for Item 1 covers:

Part A: Convert CodingSessionEditor to purely client-side
- Remove server-side loader
- Add client-side data fetching hook with useEffect
- Get JWT from useAuth() hook
- Handle loading/error states in component
Part B: Reorganize views into views/server/ and views/client/ subfolders
- server/ = views with loaders (supports both SSG and SSR)
- client/ = views without loaders (data fetched after mount)
Part C: Update routes.ts with new paths

Key insight: Server-side loaders can't access client-side state (like JWT in localStorage), which is why CodingSessionEditor's save/delete had empty JWT placeholders. Making it purely client-side solves this.

Exited plan mode

Work interrupted

what is the difference between CodingSesssion.tsx and CodingSessionPage.tsx

Let me read both files to explain the distinction:

The two components are nearly identical - both just render CodingSessionLayout. The difference is:

File	Route	Purpose
`CodingSession.tsx`	`/project/:projectId/session/:sessionId`	Page 1 (base URL, no page number)
`CodingSessionPage.tsx`	`/project/:projectId/session/:sessionId/page/:pageNumber`	Pages 2+ (with page number param)

Both use the same layout component - the real difference is in their loaders. Let me check those:

The loaders have key differences:

codingSessionLoader.ts (page 1):

No pageNumber URL param
Hardcodes currentPage = 1

codingSessionPageLoader.ts (pages 2+):

Has pageNumber param from URL
Parses pageNumber from string
Redirects /page/1 to base URL (avoids duplicate content for SEO)
Validates page number is in valid range

Why two separate route files?

Different URL patterns:
- /project/:projectId/session/:sessionId - base URL, page 1 implied
- /project/:projectId/session/:sessionId/page/:pageNumber - explicit page number
Type safety: Each loader has correctly typed params (one has pageNumber, one doesn't)
SEO: Canonical URL for page 1 is the base URL, not /page/1

Both components render the same CodingSessionLayout - the separation is purely for URL routing and loader logic. They should definitely stay together in the CodingSession/ folder since they're tightly coupled.

Does this answer your question, or would you like me to continue with exiting plan mode?

jeff

Is CodingSessionPage.tsx only there to support Pagination of large CodingSessions?

Claude

Yes, exactly. CodingSessionPage.tsx exists only to support pagination of large coding sessions.

If pagination didn't exist:

You'd only have CodingSession.tsx serving all content at /project/:projectId/session/:sessionId
There would be no /page/:pageNumber routes
No need for CodingSessionPage.tsx or codingSessionPageLoader.ts

The pagination system splits large sessions across multiple URLs:

Page 1: /project/foo/session/bar (handled by CodingSession.tsx)
Page 2+: /project/foo/session/bar/page/2 (handled by CodingSessionPage.tsx)

This is relevant to your item 2 (pagination improvements) - the current architecture with separate route files for page 1 vs pages 2+ is specifically to support SSG pre-rendering of paginated content.

Ready to exit plan mode for item 1, or do you have more questions?

jeff

We will deal with Pagination in the next topic, so let's ignore it, but just an fyi - I don't like the CodingSessionPage.tsx name because it is confusing, we should name it CodingSessionPagination.tsx - we can discuss it more later. Thanks!

Claude

Good point - CodingSessionPagination.tsx is much clearer. I'll note that for the pagination discussion in item 2.

Let me add a quick note to the plan and then exit:

Exited plan mode

Plan approved

Let me start with Part A. First, let me check what client-side API utilities exist:

Let me check how the server functions work to understand if they can be used client-side:

I see - the server functions use loadConfig() which provides internal URLs. For client-side, I need to use external URLs. Let me check the hooks:

I see - useAuth() provides login.authToken as the JWT. But useConfig() uses outlet context which requires being inside a layout. Let me check the root and config:

I see the issue - useConfig() requires being inside a layout with outlet context, but CodingSessionEditor is outside SiteLayout. Let me check how config is provided:

I see the pattern. SiteLayout has a loader that provides config via outlet context. For CodingSessionEditor to access config, I have a few options:

Option 1: Create a ClientLayout wrapper
A minimal layout with a loader that provides config, but no header/footer. CodingSessionEditor would be nested inside it and use useConfig().

Option 2: Create a global ConfigContext in root.tsx
Make config available everywhere without outlet context.

Option 3: Use Vite env vars for external URLs
Expose VITE_API_URI_EXTERNAL etc. for client-side access.

I think Option 1 is cleanest - it maintains the same pattern. Let me create a ClientLayout that just provides config:

Now I need to create client-side API functions. Let me check the sessionContent server function first:

I see a problem - the server's getSessionData uses Node.js's zlib.gunzipSync which won't work in browser. Let me check what dependencies exist:

I see the challenge - both read and write operations use Node.js zlib. I'll add pako for browser-compatible gzip handling. Let me add it and create the client API utilities:

Now let me create the client-side API utilities:

Now let me create the client-side data loading hook for the editor:

Now let me update the CodingSessionEditor component to use the client-side hook:

Now I'll rewrite the CodingSessionEditor to be fully client-side:

Now I need to delete the old loader file and update routes.ts to use ClientLayout:

Now let me run typecheck to verify everything compiles:

Two issues to fix:

I see the issue - CwcCodingSession has projectPkId (number) but ownedProjects contains project ID strings. I should use the projectId from the URL params instead. Let me fix both files:

Typecheck passes. Let me update the todo list and move to Part B:

Now let me reorganize the views into server/ and client/ subfolders:

The relative imports need to be updated since views are now one level deeper. Let me fix them:

The imports should use @/ path aliases instead of relative paths. Let me update all affected files:

Typecheck passes. Let me complete the todo:

Item 1 Complete!

Here's a summary of what was done:

Part A: Convert CodingSessionEditor to Purely Client-Side

New files created:

src/clientApi/clientApi.ts - Browser-compatible API utilities using pako for gzip
src/clientApi/index.ts - Barrel export
src/layouts/ClientLayout/ClientLayout.tsx - Minimal layout providing config context
src/layouts/ClientLayout/index.ts - Barrel export
src/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData.ts - Client-side data fetching hook

Files modified:

src/views/client/CodingSessionEditor/CodingSessionEditor.tsx - Removed loader, uses hook for data fetching
src/views/client/CodingSessionEditor/index.ts - Removed loader export

Files deleted:

codingSessionEditorLoader.ts (server-side loader)

Dependencies added:

pako + @types/pako for browser-compatible gzip

Part B: Reorganize Views

New folder structure:

src/views/
├── server/           # Views with server loaders (SSG/SSR)
│   ├── About/
│   ├── CodingSession/
│   ├── Home/
│   ├── PrivacyPolicy/
│   ├── Project/
│   └── ProjectList/
└── client/           # Views without loaders (client-rendered)
    ├── CodingSessionEditor/
    └── Logon/

Part C: Updated routes.ts

Routes now use the new paths and CodingSessionEditor is wrapped with ClientLayout for config context.

Ready to move on to Item 2: Coding Session Content Pagination when you are!

jeff

I have been pushing hard to get things done, and in the process have been slack about unit testing. Let's try to do better at that starting now. Let's setup unit tests for the Logon page and the CodingSessionEditor page and it's components please.

Claude

Good call on improving test coverage. Let me first check what testing setup exists in cwc-website:

Now I understand the testing setup. Let me set up Jest + React Testing Library for cwc-website following the monorepo patterns:

System

Claude

I'll continue by running the Logon tests to verify they pass, then proceed to the CodingSessionEditor tests.

Jest 30 changed the CLI option. Let me update the test command:

The ESM mode requires importing jest from @jest/globals. Let me fix the setup file:

The hooks.mock.ts also needs to import jest:

I need to add TextEncoder polyfill for jsdom:

The test file also needs the jest import. Let me update it:

The issue is that the mocks need to include the outlet context properly. The Logon component uses useConfig() which calls useOutletContext(). I need to set up the outlet context with the config. Let me update the mocks approach:

Let me check if there's an issue with how ESM mocks work. The problem is that in ESM mode, jest.mock at module level in a separate file might not be hoisting properly. Let me update the router mock to set up outlet context with config by default:

The issue is with ESM module mocking. Let me restructure the approach by importing mocks in setup.ts and setting proper defaults:

Let me update the setup file to import and initialize the mocks:

Now let me update the router mock to include config in outlet context by default:

The mocks aren't being applied in ESM mode. Let me try using jest.unstable_mockModule with dynamic imports, which is the proper ESM mocking pattern:

All 16 Logon tests pass. The key was using jest.unstable_mockModule with dynamic imports for proper ESM mocking. Let me update the todo and proceed to CodingSessionEditor tests:

Now let me create the first tests for CodingSessionEditor. I'll focus on testing the different states (loading, error, unauthorized, ready):

All 10 tests pass. Now let me create tests for the useCodingSessionEditorData hook:

All 12 hook tests pass. Let me run all the tests together:

All 38 tests pass. Let me clean up the setup file since the mock imports aren't needed with the ESM approach:

Unit testing setup is complete. Here's a summary of what was accomplished:

Test Setup Complete

Jest Configuration

Added Jest 30 with ts-jest preset for ESM TypeScript
Configured jsdom test environment for React component testing
Set up path aliases (@/) and CSS mocking
Added setupFilesAfterEnv for TextEncoder polyfill and jest-dom matchers

Key ESM Pattern Discovered

For Jest 30 with ESM modules, jest.unstable_mockModule() must be used instead of jest.mock(), with dynamic imports:

// 1. Set up mocks BEFORE importing
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  // ...
}));

// 2. Dynamic import AFTER mocks
const { default: Logon } = await import('@/views/client/Logon/Logon');

Tests Created

Test Suite	Tests	Description
`Logon.test.tsx`	16	Form rendering, input, submission, auth redirects
`CodingSessionEditor.test.tsx`	10	Loading/error/unauthorized/ready states
`useCodingSessionEditorData.test.ts`	12	Hook validation, auth, data loading
Total	38	All passing

Files Created/Modified

packages/cwc-website/jest.config.js - Jest configuration
packages/cwc-website/src/__tests__/setup.ts - Test setup with polyfills
packages/cwc-website/src/__tests__/mocks/ - Mock utilities (reference)
packages/cwc-website/src/__tests__/views/client/Logon/Logon.test.tsx
packages/cwc-website/src/__tests__/views/client/CodingSessionEditor/CodingSessionEditor.test.tsx
packages/cwc-website/src/__tests__/views/client/CodingSessionEditor/useCodingSessionEditorData.test.ts

Run tests with: NODE_ENV=unit pnpm --filter cwc-website test

jeff

can you run typecheck on cwc-website please, I am seeing ts errors in both the vscode editor and when I run typecheck

Claude

I see several TypeScript issues. Let me fix them:

First, let me add proper type declarations for jest-dom matchers:

Let me create a type declaration file for jest-dom matchers and fix the mock types:

Now let me fix the test files. First, let me check the types we need:

Now let me fix the test files. First, the CodingSessionEditor test:

Now let me fix the useCodingSessionEditorData test with proper mock types:

Now I understand the types. Let me fix the mock helpers. First the CodingSessionEditor test:

Now I need to fix the jest-dom type declarations. Let me check the tsconfig and update the approach:

The tsconfig has explicit types which limits type declarations. Let me update it to include jest types:

Let me update the mock helpers with the stats field and create a proper jest-dom type declaration:

Now let me create a proper type declaration for jest-dom matchers:

System

Claude

I'll continue fixing the jest-dom TypeScript errors. The issue is that Jest 30 with @jest/globals uses a different type system than traditional Jest. Let me try a different approach for the type declarations.

There's a jest-globals.d.ts file specifically for @jest/globals - this is what I need for Jest 30's ESM mode.

I found the solution. The @testing-library/jest-dom package has a specific entry point for @jest/globals users: @testing-library/jest-dom/jest-globals. This extends the correct @jest/expect module.

Let me update the setup file and remove the custom type declaration:

Now let me delete the custom type declaration file since it's no longer needed:

Let me run the typecheck to see if the changes fixed the jest-dom matcher type errors:

Typecheck passes. Let me also verify that all tests still pass:

All TypeScript errors are fixed and all 38 tests continue to pass.

Fix summary:

The issue was that @testing-library/jest-dom has a specific entry point for Jest 30 + @jest/globals users:

Before: import '@testing-library/jest-dom' - designed for traditional Jest global expect
After: import '@testing-library/jest-dom/jest-globals' - designed for @jest/globals imports

This entry point includes proper type declarations that extend @jest/expect module's Matchers interface, which is what Jest 30 ESM mode uses.

Changes made:

Updated setup.ts to import from @testing-library/jest-dom/jest-globals
Removed the custom testing-library.d.ts file (no longer needed)

jeff

very nice work! In the test files, I see around 5 separate mocks for config. Is there a way to consolidate that as well as any other mocks that are duplicated or likely to be useful as we build more unit tests?

Claude

Good idea. Let me analyze the duplicated mocks across the test files and create a shared mock structure.

I can see the shared mock files already exist but aren't being used effectively. The test files duplicate the definitions instead of importing them. Let me consolidate:

Create entities.mock.ts for CodingSession/SessionData mock helpers
Remove duplicate mockConfig from router.mock.tsx
Remove the non-functional jest.mock() calls (they don't work in ESM mode)
Update test files to import from shared mocks

Now let me update the test files to use the shared mocks. Starting with useCodingSessionEditorData.test.ts:

Now let me update Logon.test.tsx to use the shared mocks:

Now let me verify everything still works:

Let me check the CwcUser type:

I see the issue - CwcUser has different fields. Let me fix the mock:

All 38 tests pass and typecheck is clean. Here's what I consolidated:

Shared Mock Files:

File	Contents
`mocks/hooks.mock.ts`	`mockConfig`, `createMockConfig`, `mockGuestLogin`, `createMockAuthenticatedLogin`
`mocks/router.mock.tsx`	`createMockFetcher`, `createMockLocation`, `MockLink`
`mocks/entities.mock.ts`	`createMockCodingSession`, `createMockSessionData`, `createMockUser`
`mocks/index.ts`	Barrel export of all mocks

Changes:

Removed 5 duplicate mockConfig definitions - now single source in hooks.mock.ts
Removed 3 duplicate mockGuestLogin definitions - now single source
Removed 3 duplicate createMockAuthenticatedLogin - now single source
Removed 2 duplicate createMockCodingSession - now in entities.mock.ts
Removed 2 duplicate createMockSessionData - now in entities.mock.ts
Removed non-functional jest.mock() calls - they don't work in ESM mode
Added createMockUser for future tests

Usage pattern in test files:

import { mockConfig, mockGuestLogin, createMockCodingSession } from '@/__tests__/mocks';

jest.unstable_mockModule('@/hooks', () => ({
  useConfig: () => mockConfig,
  // ...
}));

jeff

thanks, that will reduce the maintenance burden on the mocks. I'm testing the CodingSessionEditor - it's getting an error when attempting to use cwc-api to fetch a CodingSession.
The payload in the request is: {sessionId: "7e6a848a-f0e0-4a10-83e0-495e287003f8"}.
This is related to another issue that I would like to address - I don't like having the CcwSessionData's sessionId (uuid) in the url for the CodingSession view.
It seems like we are using the CwcSessionData sessionId everywhere and I would like to shift to using the database table codingSession.codingSessionPkId if possible.
Can you analyze the cwc-api and cwc-website, and any other relevant packages, to determine if we can make this change?

Claude

This is a different task from the previous plan. Let me explore the codebase to understand how sessionId vs codingSessionPkId are currently used.

Excellent analysis from the explore agents. I now have a clear picture of the current architecture:

Current State Summary

Identifier	Type	Used For
`sessionId`	UUID (36 chars)	URLs, GET API calls, import correlation
`codingSessionPkId`	Integer	UPDATE/DELETE API calls, FK relationships
`storageKey`	String	Content storage in cwc-storage

The immediate error you're seeing is likely because the payload {sessionId: "7e6a848a-..."} is going to /codingSession/get which looks up by sessionId - so the API structure is correct, but something else may be failing (auth, network, etc.).

However, your broader request to switch from UUID to PkId in URLs is feasible. Before I design the implementation plan, I have a few clarifying questions:

Claude is asking...

URL FormatWhich identifier would you prefer to use in URLs going forward?

codingSessionPkId (integer)- Shorter URLs like /project/myapp/session/42 - exposes DB primary key

Keep sessionId (UUID)- Current format /project/myapp/session/7e6a848a-... - matches Claude Code transcript

API DesignShould the cwc-api GET endpoint support both identifiers, or switch entirely?

Support both (Recommended)- Accept either sessionId OR codingSessionPkId - backwards compatible, flexible

Switch to PkId only- Only accept codingSessionPkId - simpler but breaking change for any external consumers

Immediate IssueDo you want me to first diagnose why the current API call is failing before planning the migration?

Yes, fix the bug first- Debug why {sessionId: "7e6a848a-..."} is failing, then plan migration

No, proceed with migration plan- The migration will likely fix the issue anyway

Developer Response

Q: Which identifier would you prefer to use in URLs going forward?

A: "good point about `exposes DB primary key` but don't we already have api routes that require a pkId, such as deleting an entity? is exposing the pkId a big deal?"

Q: Should the cwc-api GET endpoint support both identifiers, or switch entirely?

A: "if we refer to the entity (in the db) by pkId and we have a storageKey, in what scenarios do we need to use the sessionId from the original transcript?"

Q: Do you want me to first diagnose why the current API call is failing before planning the migration?

A: "No, proceed with migration plan"

Great questions! Let me clarify:

On exposing PkId:
You're right - we already expose codingSessionPkId in UPDATE/DELETE APIs, so exposing it in URLs is consistent. The main concerns with PkId in URLs (sequential enumeration, revealing total count) are minimal risks for a public coding session site where published sessions are meant to be discoverable anyway.

On sessionId usage:
After analysis, sessionId (UUID from transcript) is only needed for:

Import deduplication - cwc-session-importer uses it to check if a session was already imported
Debug correlation - matching a DB record back to the original Claude Code transcript

It does NOT need to be in URLs or used for runtime lookups. The storageKey is independent and sufficient for content retrieval.

Now let me launch a Plan agent to design the migration:

Excellent! The Plan agent has provided a comprehensive implementation plan. Let me write this to the plan file:

File	Change
`views/server/Project/codingSessionColumn.tsx`	Links in table rows
`views/server/CodingSession/conversation/PaginationNav.tsx`	Page navigation links
`views/server/CodingSession/conversation/ConversationViewer.tsx`	Pass PkId to PaginationNav
`views/server/CodingSession/CodingSessionLayout.tsx`	Pass PkId to ConversationViewer
`views/client/CodingSessionEditor/components/EditorToolbar.tsx`	Cancel link, props

The plan is complete. Here's a summary:

Migration: sessionId → codingSessionPkId

Scope: 7 phases across cwc-api and cwc-website

Key Changes:

cwc-api: Change GetCodingSessionPayload to use codingSessionPkId (number) instead of sessionId (string)
cwc-website routes: Change :sessionId to :codingSessionPkId in URL patterns
All loaders/components: Update to extract and use integer PkId
All links: Construct URLs with session.codingSessionPkId
Tests: Update mocks and assertions

Result: URLs change from /project/myapp/session/7e6a848a-f0e0-4a10-83e0-495e287003f8 to /project/myapp/session/42

What stays the same:

sessionId column remains in database (for import deduplication)
storageKey continues to be used for content retrieval
UPDATE/DELETE operations already use codingSessionPkId - no change needed

Exited plan mode

Work interrupted

with this change, the url for the CodingSession page will be like `https://codingwithclaude.dev/project/coding-with-claude/session/12` right? Why can't we simplify it to `https://codingwithclaude.dev/session/12`? when we lookup the coding session via cwc-api with pkId=12, we will get the projectPkId and can fetch the project entity as well.

Excellent point! Since codingSessionPkId is globally unique, we don't need projectId in the session URL at all. Let me update the plan:

File	Old URL	New URL
`views/server/Project/codingSessionColumn.tsx`	`/project/${projectId}/session/${session.sessionId}`	`/session/${session.codingSessionPkId}`
`views/server/CodingSession/conversation/PaginationNav.tsx`	`/project/${projectId}/session/${sessionId}/page/${n}`	`/session/${codingSessionPkId}/page/${n}`
`views/client/CodingSessionEditor/components/EditorToolbar.tsx`	`/project/${projectId}/session/${sessionId}`	`/session/${codingSessionPkId}`

I've updated the plan to use simplified URLs: /session/42 instead of /project/myapp/session/uuid.

One question before we proceed:

Claude is asking...

Project LookupThe loader needs to fetch project details using session.projectPkId. How should we handle this?

Extend getCodingSession response (Recommended)- Modify cwc-api to JOIN project table and return project.projectId in the session response - single API call

Add getProjectByPkId endpoint- Create new cwc-api endpoint to fetch project by PkId - requires second API call

I'll check what exists first- Let me verify what cwc-api currently supports before deciding

Developer Response

Q: The loader needs to fetch project details using session.projectPkId. How should we handle this?

A: "there are a number of options here. it seems to me that we would want the ability to get a project by pkId for other use cases. 1. we could create a `codingSessionInfo` view that does the join and contains all of the fields that we are interested in. 2. we could create a separate query in cwc-api that uses getProject (add support for payload with either pkId or projectId) and getCodingSession and combines the results. There are other options, let's identify them all and choose the approach that we will follow consistently. "

Good thinking - let's identify all the options for a consistent pattern. Let me add this analysis to the plan:

Pros	Cons
Single query, all data	New view + type to maintain
SQL handles the join efficiently	View changes require migration
Clean separation from base table

Pros	Cons
Reusable for other use cases	Two API calls needed
Consistent with PkId migration	Slightly more latency
No schema changes

Pros	Cons
Single API call	Couples session API to project
No schema changes	May return more data than needed
	Different response type

Pros	Cons
Clear intent	Yet another endpoint
Can include all related data	More API surface
Optimized for this use case

Pros	Cons
No cwc-api changes (if B exists)	Two API calls
Flexible	More complex loader logic

I've added all the options to the plan. Let me ask which approach you prefer:

Claude is asking...

Data PatternWhich approach do you want to use for fetching related entity data?

Option A: Database View- codingSessionInfo view with JOINs - single query, all data, but requires schema changes

Option B: Modify getProject (Recommended)- Accept projectPkId OR projectId - reusable pattern for all entities, two API calls

Option C: Extend getCodingSession- JOIN project data in handler - single API call but couples the response

Option D: New composite endpoint- getCodingSessionDetail - purpose-built but adds API surface

Work interrupted

jeff

[Request interrupted by user for tool use]

I also like Option B since we don't need new types or routes. Another consideration is that making 2 api calls on the server for SSG will not be much of a performance hit.
I can't remember if I already mentioned this - let's also add a revised url for the CodingSessionEditor, in my opinion it should be simple like the CodingSession url.

Claude

Good point about SSG - the two API calls happen at build time, not on every request, so performance is not a concern.

Let me update the plan to confirm Option B and ensure the CodingSessionEditor URL is clearly simplified:

Page	Old URL	New URL
CodingSession	`/project/myapp/session/7e6a848a-...`	`/session/42`
CodingSession (paginated)	`/project/myapp/session/7e6a848a-.../page/2`	`/session/42/page/2`
CodingSessionEditor	`/project/myapp/session/7e6a848a-.../edit`	`/session/42/edit`

The plan is now complete with:

Option B confirmed for fetching related entity data (modify getProject to accept PkId)
Clear URL summary showing all three simplified URLs:
- /session/42 - View
- /session/42/page/2 - Paginated view
- /session/42/edit - Editor

Ready for approval?

Exited plan mode

Work interrupted

Is there a reason why the url for CodingSessionEditor (a purely client-side view) should be connected/tied to the CodingSession page url?
` | CodingSessionEditor       | /project/myapp/session/7e6a848a-.../edit   | /session/42/edit   |`
I would rather have a url like `/coding-session-editor/42`.

Good point! Since the CodingSessionEditor is a purely client-side view with different auth requirements, there's no need to tie its URL structure to the CodingSession view. Let me update:

Page	Old URL	New URL
CodingSession (SSG)	`/project/myapp/session/7e6a848a-...`	`/session/42`
CodingSession paginated (SSG)	`/project/myapp/session/7e6a848a-.../page/2`	`/session/42/page/2`
CodingSessionEditor (client)	`/project/myapp/session/7e6a848a-.../edit`	`/coding-session-editor/42`

File	Old URL	New URL
`views/server/Project/codingSessionColumn.tsx` (view link)	`/project/${projectId}/session/${session.sessionId}`	`/session/${session.codingSessionPkId}`
`views/server/Project/codingSessionColumn.tsx` (edit link)	`/project/${projectId}/session/${session.sessionId}/edit`	`/coding-session-editor/${session.codingSessionPkId}`
`views/server/CodingSession/conversation/PaginationNav.tsx`	`/project/${projectId}/session/${sessionId}/page/${n}`	`/session/${codingSessionPkId}/page/${n}`
`views/client/CodingSessionEditor/components/EditorToolbar.tsx` (cancel)	`/project/${projectId}/session/${sessionId}`	`/session/${codingSessionPkId}`

Plan updated with the separate editor URL pattern:

SSG views: /session/42, /session/42/page/2
Client editor: /coding-session-editor/42

Ready for approval?

Exited plan mode

Work interrupted

actually, lets change `/coding-session-editor/42` to `/session-editor/42` even though I like to be very explicit in my naming, we already using `/session...` and it results in a shorter url.

System

Claude

I'll continue updating the plan file to complete the URL pattern change from /coding-session-editor/ to /session-editor/.

I see the plan file. I need to update Phase 5 (Link Construction table) and the URL Summary table to use /session-editor/ instead of /coding-session-editor/.

File	Old URL	New URL
`views/server/Project/codingSessionColumn.tsx` (view link)	`/project/${projectId}/session/${session.sessionId}`	`/session/${session.codingSessionPkId}`
`views/server/Project/codingSessionColumn.tsx` (edit link)	`/project/${projectId}/session/${session.sessionId}/edit`	`/session-editor/${session.codingSessionPkId}`
`views/server/CodingSession/conversation/PaginationNav.tsx`	`/project/${projectId}/session/${sessionId}/page/${n}`	`/session/${codingSessionPkId}/page/${n}`
`views/client/CodingSessionEditor/components/EditorToolbar.tsx` (cancel)	`/project/${projectId}/session/${sessionId}`	`/session/${codingSessionPkId}`

Now I'll update the URL Summary table:

Page	Old URL	New URL
CodingSession (SSG)	`/project/myapp/session/7e6a848a-...`	`/session/42`
CodingSession paginated (SSG)	`/project/myapp/session/7e6a848a-.../page/2`	`/session/42/page/2`
CodingSessionEditor (client)	`/project/myapp/session/7e6a848a-.../edit`	`/session-editor/42`

The plan file is now complete with all URL patterns updated to use /session-editor/ instead of /coding-session-editor/.

Final URL Summary:

Page	New URL
CodingSession (SSG)	`/session/42`
CodingSession paginated (SSG)	`/session/42/page/2`
CodingSessionEditor (client)	`/session-editor/42`

The plan covers 7 phases:

cwc-api - Update payload type and GET handler to use codingSessionPkId
Routes - Simplified route definitions
Server loaders - Derive project from session's projectPkId
Client-side - Update editor data fetching and navigation
Link construction - Update all URL builders
SSG prerender - Update route discovery
Tests - Update mocks and assertions

Exited plan mode

Work interrupted

`- Update navigation after save: navigate(/session/${codingSessionPkId})` I would like the CodingSessionEditor to allow a user to Save and remain on the editor page.

Good catch. I'll update the plan to reflect that saving should keep the user on the editor page (no navigation after save).

Updated. The plan now specifies that saving keeps the user on the editor page. Ready to proceed.

Exited plan mode

Plan approved

Let me set up the task list and begin implementation.

Starting with Phase 1: cwc-api changes. Let me read the current implementation:

Let me check the existing SQL functions for coding sessions:

selectCodingSession already accepts codingSessionPkId. Now I'll update the API payload type and handler.

Now I need to also implement Option B from the plan - updating getProject to accept projectPkId OR projectId. Let me check the current project SQL functions and types:

Good, there's already selectProject (for projectPkId) and selectProjectById (for projectId). Let me check the getProject handler:

Now I'll update GetProjectPayload to support both projectPkId and projectId:

Now I'll update the getProject handler to support both identifiers:

Let me run typecheck for cwc-api to verify the changes:

cwc-api typechecks. Let me update progress and move to Phase 2:

Phase 2 complete. Let me update to Phase 3 and read the server-side loaders:

Let me check the server-side API functions:

I need to update the server API functions. Let me update them to support the new payload types:

Let me check if getProjectByPkId needs to be exported from the server index:

Now I'll update the loaders. First codingSessionLoader.ts:

Now update codingSessionPageLoader.ts:

Now let me check and update the pagination cache (uses getCachedPagination):

I need to update the pagination cache to use codingSessionPkId: number instead of sessionId: string:

I need to update calculatePagination to accept codingSessionPkId as a parameter:

Now I need to update the loaders to pass codingSessionPkId to calculatePagination:

Now let me update the todo list and move to Phase 6 (SSG Prerender):

Now let me move to Phase 5 (Link Construction):

Now let me update PaginationNav.tsx:

Now let me read and update EditorToolbar.tsx:

Now I need to find and update callers of these components. Let me search for usages:

Now let me check and update the parent view components that call these:

Now update CodingSession.tsx:

Let me check the Project view that uses CodingSessionList:

Now let me move to Phase 4 (Client-side API and hooks):

I need to add clientGetProjectByPkId to the client API first, then update the hook:

Now update the hook:

System

Claude

Continuing with Phase 4 - updating CodingSessionEditor.tsx to use the new hook signature.

Now I'll update CodingSessionEditor.tsx to use the new hook signature and updated URLs:

Now update the call to CodingSessionEditorContent to include codingSessionPkId:

Now update the CodingSessionEditorContent props type to include codingSessionPkId:

Now update handleSave to NOT navigate after save (user stays on editor page):

Now update the EditorToolbar call to pass codingSessionPkId:

I need to check if markSaved exists in the useSessionEditor hook:

The hook doesn't have a markSaved function. I need to add it to properly reset the dirty state after saving. Let me update the hook:

Now update the hook implementation to add markSaved and use refs for dirty tracking:

Now add the markSaved function and include it in the return:

Now add markSaved to the return object:

Let me check the clientApi barrel export to add clientGetProjectByPkId:

Now let me run typecheck to identify any remaining issues:

The typecheck shows test file errors. The hook now takes 1 argument instead of 2. Let me fix the test file:

The test file needs significant updates for the new hook signature. Let me rewrite it:

Let me check if createMockProject exists in the mocks file:

I need to add createMockProject function to the mocks:

Now let me check and update the mocks barrel export:

Let me run typecheck again to see if there are more issues:

Let me check what the valid project types are:

Typecheck passes for cwc-website. Now let me run the full typecheck across all packages:

All packages typecheck successfully. Let me update the todo list and run tests:

One test fails - the "Go Back" button now navigates to "/" since we no longer have projectId in the URL. Let me fix this test:

The test file needs updates for the new URL params. Let me update it:

Now update the tests to use codingSessionPkId and fix the navigation expectations:

Now let's run the tests again:

All tests pass. Let me update the todo list:

All phases of the migration are complete. Here's a summary of the changes made:

Summary: Simplified Session URLs with codingSessionPkId

URL Changes

Session View: /project/myapp/session/uuid → /session/42
Session Page: /project/myapp/session/uuid/page/2 → /session/42/page/2
Session Editor: /project/myapp/session/uuid/edit → /session-editor/42

Key Changes by Phase

Phase 1 - cwc-api:

Changed GetCodingSessionPayload from sessionId: string to codingSessionPkId: number
Updated GetProjectPayload to accept either projectId or projectPkId

Phase 2 - Routes:

Updated route definitions to use codingSessionPkId param

Phase 3 - Server Loaders:

Updated loaders to derive projectId from session.projectPkId
Added getProjectByPkId server function

Phase 4 - Client-side:

Updated clientGetCodingSession to accept codingSessionPkId: number
Added clientGetProjectByPkId function
Updated useCodingSessionEditorData hook to single param
Added markSaved() to useSessionEditor hook for save-and-stay behavior

Phase 5 - Links:

Updated all components to construct /session/N URLs
EditorToolbar now takes only codingSessionPkId

Phase 6 - Prerender:

Updated SSG route discovery to use new URL patterns

Phase 7 - Tests:

Updated all test files with new hook signatures
Added createMockProject factory function

Additional Features

Save-and-stay: CodingSessionEditor now stays on the editor page after save (per user request)
Dirty tracking: useSessionEditor hook tracks saved state to reset dirty flags

jeff

While reviewing the code, I accidentally discarded the changes to packages/cwc-website/src/prerender/prerender.ts. I reinstated your changes, but can you verify that the file matches what you would expect based on your recent work?

Claude

Let me read the current state of the file to verify it matches the expected changes:

Tool Result

     1→/**
     2→ * Pre-render route discovery for static site generation
     3→ *
     4→ * This module discovers all routes that need to be pre-rendered at build time.
     5→ * It fetches project and session data from the API to generate paths for dynamic routes.
     6→ *
     7→ * Usage in react-router.config.ts:
     8→ *   import { discoverRoutes } from './src/prerender';
     9→ *   export default { prerender: discoverRoutes } satisfies Config;
    10→ */
    11→
    12→import { loadConfig } from '../config';
    13→import { fetchAllProjects, fetchSessionsForProject, fetchSessionData } from './prerenderApi';
    14→import { calculatePagination } from './sessionPagination';
    15→
    16→/**
    17→ * Parameters passed to the prerender function by React Router
    18→ */
    19→type PrerenderParams = {
    20→  getStaticPaths: () => string[];
    21→};
    22→
    23→/**
    24→ * Discover all routes to pre-render
    25→ *
    26→ * Returns an array of all URL paths that should be pre-rendered at build time.
    27→ *
    28→ * Static routes are discovered automatically via getStaticPaths().
    29→ * Dynamic routes (projects, sessions) are discovered by fetching from the API.
    30→ *
    31→ * In 'Minimal' content mode, only static routes are pre-rendered (no projects/sessions).
    32→ */
    33→export async function discoverRoutes({ getStaticPaths }: PrerenderParams): Promise<string[]> {
    34→  console.log('[prerender] Starting route discovery...');
    35→  const startTime = Date.now();
    36→
    37→  // Load config to check content mode
    38→  const config = loadConfig();
    39→  console.log(`[prerender] Content mode: ${config.websiteContentMode}`);
    40→
    41→  // 1. Get static routes automatically (/, /about, /privacy-policy)
    42→  const staticPaths = getStaticPaths();
    43→  console.log(`[prerender] Static paths: ${staticPaths.join(', ')}`);
    44→
    45→  // For Minimal mode, only pre-render static routes (no projects/sessions)
    46→  if (config.websiteContentMode === 'Minimal') {
    47→    // Filter out /projects from static paths in Minimal mode
    48→    const minimalPaths = staticPaths.filter((p) => p !== '/projects');
    49→    const elapsed = Date.now() - startTime;
    50→    console.log(`[prerender] Minimal mode - skipping project/session discovery`);
    51→    console.log(`[prerender] Route discovery complete in ${elapsed}ms`);
    52→    console.log(`[prerender] Total paths to pre-render: ${minimalPaths.length}`);
    53→    return minimalPaths;
    54→  }
    55→
    56→  // 2. Add /projects (list page)
    57→  const allPaths: string[] = [...staticPaths, '/projects'];
    58→
    59→  // 3. Fetch all projects and their sessions
    60→  const projects = await fetchAllProjects();
    61→
    62→  for (const project of projects) {
    63→    // Add project page
    64→    const projectPath = `/project/${project.projectId}`;
    65→    allPaths.push(projectPath);
    66→
    67→    // Fetch sessions for this project
    68→    const sessions = await fetchSessionsForProject(project.projectPkId);
    69→
    70→    for (const session of sessions) {
    71→      // Base session path (page 1) - uses codingSessionPkId for simplified URL
    72→      const sessionBasePath = `/session/${session.codingSessionPkId}`;
    73→      allPaths.push(sessionBasePath);
    74→
    75→      // Fetch session data to calculate pagination
    76→      if (session.storageKey) {
    77→        const sessionData = await fetchSessionData(project.projectId, session.storageKey);
    78→
    79→        if (sessionData) {
    80→          const paginationInfo = calculatePagination(session.codingSessionPkId, sessionData);
    81→
    82→          // Add paginated routes (page 2+)
    83→          for (let page = 2; page <= paginationInfo.totalPages; page++) {
    84→            allPaths.push(`${sessionBasePath}/page/${page}`);
    85→          }
    86→
    87→          if (paginationInfo.totalPages > 1) {
    88→            console.log(
    89→              `[prerender]   Session ${session.codingSessionPkId}: ${paginationInfo.totalPages} pages`
    90→            );
    91→          }
    92→        }
    93→      }
    94→    }
    95→
    96→    console.log(`[prerender] Project "${project.projectId}": ${sessions.length} sessions`);
    97→  }
    98→
    99→  const elapsed = Date.now() - startTime;
   100→  console.log(`[prerender] Route discovery complete in ${elapsed}ms`);
   101→  console.log(`[prerender] Total paths to pre-render: ${allPaths.length}`);
   102→
   103→  return allPaths;
   104→}
   105→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

The file looks correct. Here are the key changes that should be present based on the migration:

Line 72: Uses simplified URL format with codingSessionPkId

const sessionBasePath = `/session/${session.codingSessionPkId}`;

Line 80: Passes codingSessionPkId to calculatePagination

const paginationInfo = calculatePagination(session.codingSessionPkId, sessionData);

Line 84: Paginated routes follow the new format

allPaths.push(`${sessionBasePath}/page/${page}`);

Line 89: Log message uses codingSessionPkId

console.log(`[prerender]   Session ${session.codingSessionPkId}: ${paginationInfo.totalPages} pages`);

All changes are correctly in place. The file will generate URLs like:

/session/42 (session view)
/session/42/page/2 (paginated session view)

Let me verify the typecheck still passes with these changes:

Typecheck passes. The prerender.ts file is correctly updated and matches the expected changes from the migration.

jeff

running the website locally pointed to test
redeployed services & nginx
clicking on a session in the SessionList (hoping to view CodingSession page) - see a lot of activity in the network tab but gets redirected back to the Project page
I turned off the network so I can see the original request:

Claude

This looks like the loader is failing and redirecting. Let me check the codingSessionLoader.ts to see if there's a redirect happening:

Let me check the server-side getCodingSession function:

Let me verify the cwc-api getCodingSession handler is correctly updated:

Let me check if the getProjectByPkId function is actually working - I need to verify the API has the proper handler:

Let me check the routes file:

Let me check the link being generated in the session list to make sure it's using the correct URL format:

The link URL /session/39 looks correct. The issue is likely that the loader is failing. Can you check what the API is actually returning?

Try this in your browser console while on the project page:

fetch('https://test.codingwithclaude.dev/api/v1/codingSession/get', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ codingSessionPkId: 39 })
}).then(r => r.json()).then(console.log)

Or check the Network tab for the /session/39.data request - what's the response status and body?

The redirect to /project/coding-with-claude suggests something is failing and React Router might be falling back. The most likely causes:

API not returning data - The /codingSession/get endpoint might still expect sessionId instead of codingSessionPkId if the cwc-api wasn't rebuilt/redeployed
Project lookup failing - The new getProjectByPkId call might not be working

jeff

shouldn't that uri be 'https://api.test.codingwithclaude.dev/api/v1/codingSession/get' instead of 'https://test.codingwithclaude.dev/api/v1/codingSession/get'?

Claude

You're right, my mistake. Try:

fetch('https://api.test.codingwithclaude.dev/api/v1/codingSession/get', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ codingSessionPkId: 39 })
}).then(r => r.json()).then(console.log)

jeff

running the fetch in the browser console:
Access to fetch at 'https://api.test.codingwithclaude.dev/api/v1/codingSession/get' from origin 'http://localhost:5173' has been blocked by CORS policy: The 'Access-Control-Allow-Origin' header contains multiple values 'test.codingwithclaude.dev, http://localhost:5173', but only one is allowed. Have the server send the header with a valid value.

Claude

That's a CORS configuration issue (duplicate headers), but let's bypass it for testing. Try from terminal instead:

curl -X POST https://api.test.codingwithclaude.dev/api/v1/codingSession/get \
  -H "Content-Type: application/json" \
  -d '{"codingSessionPkId": 39}'

This will show us if the API is correctly accepting codingSessionPkId or if it's still expecting the old sessionId parameter.

jeff

~ % curl -X POST https://api.test.codingwithclaude.dev/api/v1/codingSession/get
-H "Content-Type: application/json"
-d '{"codingSessionPkId": 39}'
{"success":true,"data":{"codingSessionPkId":39,"enabled":1,"createdDate":"2025-12-31 19:09:17","modifiedDate":"2025-12-31 19:09:17","userPkId":1,"projectPkId":1,"description":"Session on main (claude-sonnet-4-5-20250929)","published":1,"sessionId":"7e6a848a-f0e0-4a10-83e0-495e287003f8","storageKey":"2025-11-17_21-51-32_7e6a848a-f0e0-4a10-83e0-495e287003f8.json.gz","startTimestamp":"2025-11-17 21:51:32","endTimestamp":"2025-11-17 23:57:43","gitBranch":"main","model":"claude-sonnet-4-5-20250929","messageCount":20,"filesModifiedCount":12}}%

Claude

The API is working correctly for getCodingSession. Now let's verify the getProjectByPkId call works (the loader uses session.projectPkId which is 1):

curl -X POST https://api.test.codingwithclaude.dev/api/v1/project/get \
  -H "Content-Type: application/json" \
  -d '{"projectPkId": 1}'

jeff

~ % curl -X POST https://api.test.codingwithclaude.dev/api/v1/project/get
-H "Content-Type: application/json"
-d '{"projectPkId": 1}'
{"success":true,"data":{"projectPkId":1,"enabled":1,"createdDate":"2025-12-29 01:28:49","modifiedDate":"2025-12-29 01:28:49","projectId":"coding-with-claude","projectSessionFolder":"coding-with-claude","projectType":"web","userPkId":1}}%

Claude

Both API endpoints work correctly. The issue is likely with the actual loader request.

Can you check the Network tab for the /session/39.data request specifically? Look at:

Response status code - Is it 200, or an error?
Response body - What does it contain?
Any CORS errors in the console when clicking the link?

The CORS issue you saw earlier (multiple Access-Control-Allow-Origin values) could be causing the .data fetch to fail, which would make React Router error out and potentially navigate away.

jeff

now it's working, but other than restarting the local website dev server (which I had done before) I'm not sure why it is working or was failing

Claude

That's a common issue with Vite/React Router dev server after significant route changes. The HMR (Hot Module Replacement) doesn't always fully update:

Route configurations
Loader function signatures
Param name changes (like sessionId → codingSessionPkId)

When you change route param names or loader dependencies, a full dev server restart is often needed to clear the cached module state.

Good to hear it's working now. The key changes are all in place:

/session/39 URLs work
API accepts codingSessionPkId
Project lookup via projectPkId works

jeff

now testing the edit link in the SessionList on the Project page
https://api.test.codingwithclaude.dev/api/v1/codingSession/get has status code 200
payload: {codingSessionPkId: 39}
no response received

Claude

The "no response received" with a 200 status suggests a CORS issue - the request succeeds but the browser can't read the response body due to the CORS misconfiguration we saw earlier (multiple Access-Control-Allow-Origin values).

Can you check the browser console for CORS errors when clicking the edit link?

The duplicate CORS header issue needs to be fixed. It's likely coming from both:

The nginx configuration adding CORS headers
The Express app also adding CORS headers

One of them needs to be removed so only a single Access-Control-Allow-Origin header is sent.

jeff

here's everything from the OPTIONS request:

Claude

Go ahead - paste the OPTIONS request headers and response.

jeff

General:
Request URL
https://api.test.codingwithclaude.dev/api/v1/codingSession/get
Request Method
OPTIONS
Status Code
204 No Content
Remote Address
50.191.242.44:443
Referrer Policy
strict-origin-when-cross-origin
access-control-allow-credentials
true

Response Headers:
access-control-allow-headers
Authorization, Content-Type, X-Requested-With
access-control-allow-methods
GET, POST, PUT, DELETE, OPTIONS
access-control-allow-origin
http://localhost:5173
access-control-max-age
1728000
content-length
0
content-type
text/plain charset=UTF-8
date
Sun, 04 Jan 2026 22:39:18 GMT
server
nginx/1.29.4

Request Headers:
:authority
api.test.codingwithclaude.dev
:method
OPTIONS
:path
/api/v1/codingSession/get
:scheme
https
accept
/
accept-encoding
gzip, deflate, br, zstd
accept-language
en-US,en;q=0.9
access-control-request-headers
content-type
access-control-request-method
POST
origin
http://localhost:5173
priority
u=1, i
referer
http://localhost:5173/
sec-fetch-dest
empty
sec-fetch-mode
cors
sec-fetch-site
cross-site
user-agent
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36

Claude

The OPTIONS preflight looks correct - single access-control-allow-origin: http://localhost:5173 header.

Can you now show the actual POST request headers/response? That's where the "no response received" issue is occurring. The preflight passed, but the actual request might have different headers.

jeff

are you able to run a curl command for that?

Claude

Tool Result

Note: Unnecessary use of -X or --request, POST is already inferred.
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed

  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* Host api.test.codingwithclaude.dev:443 was resolved.
* IPv6: (none)
* IPv4: 50.191.242.44
*   Trying 50.191.242.44:443...
* Connected to api.test.codingwithclaude.dev (50.191.242.44) port 443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
} [334 bytes data]
*  CAfile: /etc/ssl/cert.pem
*  CApath: none
* (304) (IN), TLS handshake, Server hello (2):
{ [122 bytes data]
* (304) (IN), TLS handshake, Unknown (8):
{ [41 bytes data]
* (304) (IN), TLS handshake, Certificate (11):
{ [2112 bytes data]
* (304) (IN), TLS handshake, CERT verify (15):
{ [79 bytes data]
* (304) (IN), TLS handshake, Finished (20):
{ [36 bytes data]
* (304) (OUT), TLS handshake, Finished (20):
} [36 bytes data]
* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=codingwithclaude.dev
*  start date: Jan  1 03:33:36 2026 GMT
*  expire date: Apr  1 03:33:35 2026 GMT
*  subjectAltName: host "api.test.codingwithclaude.dev" matched cert's "*.test.codingwithclaude.dev"
*  issuer: C=US; O=Let's Encrypt; CN=E8
*  SSL certificate verify ok.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://api.test.codingwithclaude.dev/api/v1/codingSession/get
* [HTTP/2] [1] [:method: POST]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: api.test.codingwithclaude.dev]
* [HTTP/2] [1] [:path: /api/v1/codingSession/get]
* [HTTP/2] [1] [user-agent: curl/8.7.1]
* [HTTP/2] [1] [accept: */*]
* [HTTP/2] [1] [content-type: application/json]
* [HTTP/2] [1] [origin: http://localhost:5173]
* [HTTP/2] [1] [content-length: 25]
> POST /api/v1/codingSession/get HTTP/2
> Host: api.test.codingwithclaude.dev
> User-Agent: curl/8.7.1
> Accept: */*
> Content-Type: application/json
> Origin: http://localhost:5173
> Content-Length: 25
> 
} [25 bytes data]
* upload completely sent off: 25 bytes
< HTTP/2 200 
< server: nginx/1.29.4
< date: Sun, 04 Jan 2026 22:48:40 GMT
< content-type: application/json; charset=utf-8
< content-length: 542
< content-security-policy: default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests
< cross-origin-opener-policy: same-origin
< cross-origin-resource-policy: same-origin
< origin-agent-cluster: ?1
< referrer-policy: no-referrer
< strict-transport-security: max-age=31536000; includeSubDomains
< x-content-type-options: nosniff
< x-dns-prefetch-control: off
< x-download-options: noopen
< x-frame-options: SAMEORIGIN
< x-permitted-cross-domain-policies: none
< x-xss-protection: 0
< access-control-allow-origin: test.codingwithclaude.dev
< vary: Origin
< access-control-allow-credentials: true
< access-control-allow-headers: Authorization, Origin, X-Requested-With, Content-Type, Accept
< access-control-allow-methods: OPTIONS,POST
< access-control-expose-headers: Authorization
< etag: W/"21e-RzJPx+baeQZHRMkQFcIUIBhwcMA"
< access-control-allow-origin: http://localhost:5173
< access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
< access-control-allow-headers: Authorization, Content-Type, X-Requested-With
< access-control-allow-credentials: true
< 
{ [542 bytes data]

100   567  100   542  100    25   2539    117 --:--:-- --:--:-- --:--:--  2661
* Connection #0 to host api.test.codingwithclaude.dev left intact
{"success":true,"data":{"codingSessionPkId":39,"enabled":1,"createdDate":"2025-12-31 19:09:17","modifiedDate":"2025-12-31 19:09:17","userPkId":1,"projectPkId":1,"description":"Session on main (claude-sonnet-4-5-20250929)","published":1,"sessionId":"7e6a848a-f0e0-4a10-83e0-495e287003f8","storageKey":"2025-11-17_21-51-32_7e6a848a-f0e0-4a10-83e0-495e287003f8.json.gz","startTimestamp":"2025-11-17 21:51:32","endTimestamp":"2025-11-17 23:57:43","gitBranch":"main","model":"claude-sonnet-4-5-20250929","messageCount":20,"filesModifiedCount":12}}

Found the issue. There are two access-control-allow-origin headers being sent:

access-control-allow-origin: test.codingwithclaude.dev   ← from Express
access-control-allow-origin: http://localhost:5173        ← from nginx

The browser rejects responses with multiple CORS origin headers.

The fix: Either nginx or the Express app should handle CORS, not both. Currently:

Express is sending test.codingwithclaude.dev (from app config)
nginx is adding http://localhost:5173 (from $http_origin)

Options:

Remove CORS headers from nginx - Let Express handle it entirely (but then Express needs to accept localhost:5173 for dev)
Remove CORS from Express - Let nginx handle it entirely
Update Express CORS config to include http://localhost:5173 in DEV_CORS_ORIGIN for test environment

Which approach would you prefer?

jeff

In the past I have handled it in the express services - probably because I didn't know how to configure that in nginx and I understand the code better than the nginx config. Ignoring my preferences, which is the best way to go? How does this decision affect prod if at all?

Claude

Best practice: Handle CORS at the nginx layer

Here's why:

Aspect	nginx (recommended)	Express
Centralization	One place for all services	Each service needs config
Performance	Preflight handled without hitting Node.js	Extra round-trip to Express
Consistency	All services get same CORS policy automatically	Risk of misconfiguration per service
Separation of concerns	Edge concerns (SSL, CORS, rate limiting) in nginx; business logic in Express	Mixed concerns

Production impact:

None, really. The same origins get allowed - it's just about where the headers come from. In prod you'd allow:

https://codingwithclaude.dev
https://www.codingwithclaude.dev

The main benefit for your situation:

With nginx handling CORS, you can have one config that says "for test environment, allow both test.codingwithclaude.dev AND localhost:5173" without touching any service code. This is cleaner than adding DEV_CORS_ORIGIN environment variables to each service.

Recommendation:

Remove CORS middleware from Express services
Configure nginx to handle CORS with environment-appropriate origins
For test: allow both the test domain and localhost
For prod: allow only production domains

Would you like me to help update the nginx config and remove CORS from the Express services?

jeff

I would like to switch to doing this with nginx, but let's comment out the code in the back-end-utils and service packages just in case we change our minds about this later.

Claude

Let me check if cors is exported from the barrel:

The nginx test config already has CORS handling (lines 116-142 for api, etc.). Now that Express CORS is disabled, nginx will be the sole source. Let me check the prod template too:

System

Claude

The CORS migration work is complete on the code side. Let me update the todo list to reflect this:

jeff

[Request interrupted by user]

thinking about this more:

this means that the nginx cors config is critical - we should have documentation emphasizing the importance that nginx cors is properly configured since we are not checking cors in the services
I'd like to get your take on this - in the nginx response I see access-control-allow-methods : GET, POST, PUT, DELETE, OPTIONS. in the service's cors implementation, we were being more granular and only allowing OPTIONS and POST, and optionally/configurable allowing GET.

Claude

These are both excellent points. Let me address each:

1. Documentation

You're right - with CORS now centralized in nginx, this becomes critical infrastructure. I should update the documentation to reflect this.

2. Method Granularity

This is a valid security concern. Here's the trade-off:

Express approach (granular):

// cwc-api: allows GET, POST, OPTIONS
createExpressService({ allowGet: true, allowPost: true, allowOptions: true })

// cwc-auth: allows POST, OPTIONS only (no GET for auth endpoints)
createExpressService({ allowGet: false, allowPost: true, allowOptions: true })

Current nginx approach (permissive):

add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;

The security implications:

Layer	What it controls
CORS preflight	Browser decides if it can attempt the request
Express routes	Server decides if the request succeeds
invalidRoutes middleware	Blocks methods not in allowGet/allowPost (returns 400)

The invalidRoutes middleware still enforces method restrictions at the service level - a DELETE request to cwc-api would be rejected with 400 even if CORS allowed it.

However, defense-in-depth argues for restricting at both layers. The question is: is it worth the nginx complexity?

Options:

Per-service nginx blocks - More secure but requires maintaining method lists in two places (nginx + service config)
Keep nginx permissive - Simpler, rely on invalidRoutes middleware as the enforcement point
Restrict nginx to actual used methods - Since we only use GET, POST, OPTIONS across all services (no PUT/DELETE), we could at minimum remove those

What's your preference? I lean toward option 3 as a reasonable middle ground - remove methods we never use (PUT, DELETE) from nginx, but not try to make it per-service granular.

jeff

Interesting, I'm kind of leaning toward using the proven express cors approach - it has worked for me in the past, the code is written and is part of our reusable Express functionality in backend-utils (so we don't have to remember to set it up for every new service), and it does what we want. how much more secure or better is the nginx approach than what we have in the code?

Claude

Honestly? For your use case, the Express approach is probably the better choice. Let me break down the real trade-offs:

nginx CORS advantages:

Slightly faster (headers added before hitting Node.js) - but we're talking microseconds
Single configuration point - but you lose per-service granularity
Industry "best practice" for high-traffic sites - but not a significant factor at your scale

Express CORS advantages:

Already written, tested, and proven in your stack
Per-service method control (allowGet, allowPost, allowOptions)
Environment-aware logic built in (isDev, isTest, isProd, devCorsOrigin)
Automatically applied via createExpressService() - new services get it free
Code is version-controlled and reviewable
You understand it

The honest answer: The nginx approach isn't meaningfully "more secure" or "better" for your use case. The main arguments for nginx CORS are:

Performance at massive scale (not applicable here)
When you have mixed backends (Python, Go, Node) needing consistent CORS (not applicable)

The root problem was duplicate headers, not "wrong approach." Either solution works - you just can't have both.

My recommendation: Revert to Express CORS and remove the CORS headers from nginx. The Express approach gives you more control and is already integrated into your service pattern.

Want me to:

Uncomment the Express CORS code
Remove the CORS headers from the nginx templates

jeff

that sounds good, thanks for helping me analyze the trade-offs

Claude

Let me restore the Express CORS and remove it from nginx.

Now let me read the nginx templates to remove the CORS headers:

Now the prod template:

Now let me run typecheck:

All done. The CORS handling has been reverted to Express middleware:

Changes made:

cwc-backend-utils/src/express/service.ts - Re-enabled CORS middleware import and usage
cwc-backend-utils/src/express/cors.ts - Restored the full implementation (also updated the troubleshooting comment to say "make sure CORS headers are NOT set in nginx")
cwc-deployment/templates/nginx/conf.d/default.conf.test.template - Removed CORS headers from api, auth, and content server blocks (added comment pointing to Express middleware)
cwc-deployment/templates/nginx/conf.d/default.conf.prod.template - Same changes as test template

To apply these changes:

Redeploy services: ./deployment-scripts/deploy-services.sh test
Redeploy nginx: ./deployment-scripts/deploy-nginx.sh test

The Express CORS middleware gives you:

Per-service method control (allowGet, allowPost, allowOptions)
Environment-aware origin handling (dev/test/prod)
devCorsOrigin support for localhost development against test services

jeff

now that we are relying on the services to handle cors, can you review all of the relevant code, including our configuration system, to verify that we are properly handling it?

Claude

I'll do a thorough review of the CORS implementation across the codebase.

Good analysis. Let me verify some specific details about the CORS origin values in the configuration:

I see a potential issue. Let me check the cors.ts middleware to see how it compares origins:

I found a critical issue. Let me verify the exact configuration values:

I found a critical bug in the CORS configuration:

Issue 1: Missing Protocol in `corsOrigin`

In configuration.ts:

prod: {
  corsOrigin: 'codingwithclaude.dev',        // ❌ Missing https://
  devCorsOrigin: 'http://localhost:3000',    // ✓ Correct
  appUrl: 'https://codingwithclaude.dev',    // ✓ Correct
},
test: {
  corsOrigin: 'test.codingwithclaude.dev',   // ❌ Missing https://
  devCorsOrigin: 'http://localhost:3000',    // ✓ Correct
  appUrl: 'https://test.codingwithclaude.dev', // ✓ Correct
},

The problem:

Browser sends: Origin: https://test.codingwithclaude.dev
Server returns: Access-Control-Allow-Origin: test.codingwithclaude.dev
Browser compares them: NO MATCH → CORS blocked

CORS requires an exact match including the protocol.

Issue 2: No Origin Validation in Test/Prod

Looking at cors.ts:

if (config.isTest) {
  if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
    res.header('Access-Control-Allow-Origin', config.devCorsOrigin);  // ✓ Validates origin
  } else {
    res.header('Access-Control-Allow-Origin', config.corsOrigin);     // ❌ Sets without validating!
  }
}

if (config.isProd) {
  res.header('Access-Control-Allow-Origin', config.corsOrigin);       // ❌ Sets without validating!
}

For test/prod, it blindly sets Access-Control-Allow-Origin to corsOrigin without checking if the incoming Origin header actually matches. This means:

Any origin can make a request and get back Access-Control-Allow-Origin: test.codingwithclaude.dev
The browser will still block it (origin mismatch), but it's a logic issue

Recommended Fix

1. Fix configuration.ts - add protocol to corsOrigin:

prod: {
  corsOrigin: 'https://codingwithclaude.dev',
  // ...
},
test: {
  corsOrigin: 'https://test.codingwithclaude.dev',
  // ...
},

2. Optionally fix cors.ts - validate origin before setting header:

if (config.isTest) {
  if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
    res.header('Access-Control-Allow-Origin', config.devCorsOrigin);
  } else if (req.headers.origin === config.corsOrigin) {
    res.header('Access-Control-Allow-Origin', config.corsOrigin);
  }
  // If neither matches, no CORS header set → browser blocks
}

Would you like me to make these fixes?

jeff

this is interesting information: CORS requires an exact match including the protocol. that doesn't line-up with my experience - what I have seen.
But if we are always running our site securely with https/ssl/tls, then it should not have any impact to provide the protocol in our cors origin config values.
Unfortunately, we are running our local dev website insecurely.
The idea/intended logic of if (config.isTest) { if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) { is for test only and if devCorsOrigin is configured then we check if the origin matches devCorsOrigin and if it matches we allow it.
regarding your concern of setting without validating, I don't think that we need to validate - the browser compares the value that we return and determines if it is okay, correct?

Claude

You're right on the validation point - I was overcomplicating it. The browser does the comparison and blocks if it doesn't match. The server just says "here's who I allow" and the browser enforces it. No security issue there.

On the protocol question - you may be right that I'm being overly strict. Let me reconsider...

Actually, I think the reason it's been working for you is that:

Local dev → Origin: http://localhost:3000 matches devCorsOrigin: 'http://localhost:3000' ✓
Previously → nginx was handling CORS with $http_origin which reflects whatever origin is sent

Now that we've switched to Express CORS, requests from https://test.codingwithclaude.dev will hit the else branch:

if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
  // localhost matches - works
} else {
  res.header('Access-Control-Allow-Origin', config.corsOrigin);  // Returns 'test.codingwithclaude.dev'
}

The question is: will the browser accept test.codingwithclaude.dev when it sent https://test.codingwithclaude.dev?

Rather than speculating, we could just test it after redeploying. If it works, great. If not, we add the protocol prefix.

Either way, adding https:// to the test/prod corsOrigin values is harmless and makes the config more explicit/consistent with how devCorsOrigin and appUrl are defined. Would you like to add it proactively, or test first and fix if needed?

jeff

when we were using next.js the local website ran on http://localhost:3000 but when we switched to React Router v7 that changed to http://localhost:5173. Did we forget to update the devCorsOrigin?

Claude

Yes! That's exactly it. Looking at the configuration:

devCorsOrigin: 'http://localhost:3000',  // ← Next.js port, not Vite/React Router

But Vite (used by React Router v7) runs on port 5173 by default.

So when you run the local website and make requests to test services:

Browser sends: Origin: http://localhost:5173
Server checks: http://localhost:5173 === http://localhost:3000 → FALSE
Falls through to: Access-Control-Allow-Origin: test.codingwithclaude.dev
Browser rejects (origin mismatch)

This was masked before because nginx was returning $http_origin (reflecting whatever origin was sent), so it worked. Now with Express-only CORS, this configuration mismatch is exposed.

Let me fix it:

Fixed. All 5 environments (prod, test, dev, unit, e2e) now have devCorsOrigin: 'http://localhost:5173'.

Next steps:

Regenerate the .env files for test (and any other environment you're using)
Redeploy services to pick up the new config
Redeploy nginx to pick up the CORS removal

Then local dev against test services should work correctly.

jeff

omg, it is working, thank you! well, it is rendering, I have not tested the functionality yet.

Claude

The CodingSessionEditor is looking good! The sensitive data search feature is impressive - detecting 38 potential sensitive items including API keys and user paths.

The URL is also using the new simplified format: /session-editor/39 (using codingSessionPkId instead of the old /project/{projectId}/session/{sessionId}/edit pattern).

Let me know how the functionality testing goes - Save, Cancel, Delete Session, and the editing features. If any issues come up, I'm here to help debug.

jeff

looking back at my original prompt for this session (can you remember back that far?), we didn't make it past the first item on the list. I think that we should tackle the rest of those topics in another session. can you review all that we have covered and update claude.md files and readme.md files as needed to capture any important decisions, reasoning, etc. please?

Claude

You're right - we spent the entire session on CORS debugging! Let me summarize what we covered and update the relevant documentation.

Session Summary

Original goal: Website improvements (multiple items)
What we actually accomplished: CORS architecture decision and configuration fix

Key Decisions & Changes:

CORS handled by Express middleware, NOT nginx
- Rationale: Per-service method control (allowGet, allowPost, allowOptions), environment-aware logic, integrated into createExpressService pattern
- Removed CORS headers from nginx templates (both test and prod)
Fixed devCorsOrigin port: 3000 → 5173
- Next.js used port 3000, React Router v7/Vite uses port 5173
- This was causing CORS failures when running local website against test services
CORS troubleshooting insight: Duplicate CORS headers (from both nginx and Express) cause browsers to reject responses

Let me update the documentation:

Now let me update the documentation:

Now let me check the configuration-helper CLAUDE.md for any relevant updates:

Let me check the root CLAUDE.md for any CORS-related content:

Good - the root CLAUDE.md doesn't have CORS content (appropriately delegated to package-level docs).

Summary of Documentation Updates

cwc-backend-utils/CLAUDE.md

Updated the "CORS Configuration" section to:

Clarify that CORS is handled exclusively by Express middleware, NOT nginx
Document this as a deliberate architectural decision (session 045)
Added critical warning about duplicate headers causing browser rejections
Updated devCorsOrigin port from 3000 to 5173 (Vite/React Router)
Added troubleshooting section for CORS issues

cwc-deployment/CLAUDE.md

Removed "(with CORS for local dev)" from nginx route descriptions
Replaced "Prod CORS" statement with explicit note that nginx does NOT handle CORS
Added cross-reference to cwc-backend-utils for CORS configuration

cwc-configuration-helper/configuration.ts (code change)

Changed devCorsOrigin from 'http://localhost:3000' to 'http://localhost:5173' across all environments

Session 045 Summary

Original goal: Multiple website improvements
Actual outcome: CORS architecture decision and configuration fix

Key changes:

Confirmed Express handles CORS (not nginx) - removed CORS from nginx templates
Fixed devCorsOrigin port: 3000 → 5173 (Next.js → Vite migration oversight)
Documented the architecture decision and troubleshooting guidance

Files modified:

cwc-backend-utils/src/express/service.ts - re-enabled CORS middleware
cwc-backend-utils/src/express/cors.ts - restored implementation
cwc-deployment/templates/nginx/conf.d/default.conf.test.template - removed CORS
cwc-deployment/templates/nginx/conf.d/default.conf.prod.template - removed CORS
cwc-configuration-helper/src/configuration.ts - fixed devCorsOrigin port
cwc-backend-utils/CLAUDE.md - documented CORS architecture
cwc-deployment/CLAUDE.md - updated nginx documentation

jeff

don't forget the vastly improved urls and organization of our server and client pages!

Claude

You're right! That was actually the main work of this session before we got sidetracked by CORS. Let me document the URL simplification.

Tool Result

     1→# cwc-website Package
     2→
     3→Public-facing React Router v7 web application with SSG (Static Site Generation) for codingwithclaude.dev.
     4→
     5→---
     6→
     7→## Technology Stack
     8→
     9→- **React 19** - UI library
    10→- **React Router v7** - Framework mode with SSG pre-rendering
    11→- **Vite** - Build tool
    12→- **SCSS** - Styling (colocated with layout templates)
    13→
    14→---
    15→
    16→## Build Modes: SSR vs SSG
    17→
    18→The website supports two deployment modes controlled by the `SSG_BUILD` environment variable:
    19→
    20→| Mode | SSG_BUILD | Pre-rendering | Use Case |
    21→|------|-----------|---------------|----------|
    22→| **SSR** | not set | Disabled | `deploy-website.sh` - Fast builds, pages render on request |
    23→| **SSG** | `true` | Enabled | `deploy-website-build.sh` - Static HTML, CDN hosting |
    24→
    25→### SSR Mode (Default)
    26→
    27→When `SSG_BUILD` is not set, the build skips pre-rendering entirely:
    28→- Pages render on each request (server-side)
    29→- No API access needed during build
    30→- Fast build times
    31→- Used by `deploy-website.sh`
    32→
    33→### SSG Mode
    34→
    35→When `SSG_BUILD=true`, React Router pre-renders all routes to static HTML:
    36→- Requires API access during build
    37→- Generates pure static files in `build/client/`
    38→- Used by `deploy-website-build.sh` (sets `SSG_BUILD=true` automatically)
    39→- **Disables fog of war** route discovery for static deployments
    40→
    41→### Route Discovery: Fog of War (CRITICAL for SSG)
    42→
    43→**Problem:** React Router v7's "fog of war" feature lazily discovers routes via `/__manifest` requests. This works for SSR but breaks SSG deployments because:
    44→- Static files have no server to respond to `/__manifest`
    45→- Client-side navigation fails with 404 errors
    46→
    47→**Solution:** Disable fog of war for SSG builds in `react-router.config.ts`:
    48→
    49→```typescript
    50→// Only pre-render when SSG_BUILD is set
    51→const isSSGBuild = process.env['SSG_BUILD'] === 'true';
    52→
    53→export default {
    54→  ssr: true,
    55→
    56→  // Disable lazy route discovery for SSG builds
    57→  // All routes are included upfront in the client bundle
    58→  routeDiscovery: isSSGBuild ? { mode: 'initial' } : undefined,
    59→
    60→  // Pre-render only for SSG builds
    61→  prerender: isSSGBuild ? discoverRoutes : false,
    62→} satisfies Config;
    63→```
    64→
    65→**What `routeDiscovery: { mode: 'initial' }` does:**
    66→- Includes ALL routes in the initial client bundle (no lazy loading)
    67→- Prevents client-side requests to `/__manifest`
    68→- Required for any static deployment (Cloudflare Pages, nginx static, etc.)
    69→
    70→**Reference:** https://github.com/remix-run/react-router/discussions/13241
    71→
    72→### Client-Side Navigation: .data Files
    73→
    74→**How React Router v7 client navigation works:**
    75→
    76→When users click links (client-side navigation), React Router fetches `.data` files instead of full HTML:
    77→- `/project/foo` → requests `/project/foo.data` (JSON with loader data)
    78→- Avoids full page reload, provides SPA-like experience
    79→
    80→**SSG output includes .data files:**
    81→```
    82→build/client/
    83→├── project/
    84→│   └── foo/
    85→│       ├── index.html    # Full HTML for initial/direct load
    86→│       └── index.data    # JSON data for client-side navigation
    87→```
    88→
    89→**Important for deployments:**
    90→- `.data` files must be served with correct MIME type
    91→- If using HTTP Basic Auth (test env), `.data` requests bypass auth because `fetch()` doesn't send credentials automatically
    92→- See cwc-deployment CLAUDE.md for nginx configuration details
    93→
    94→## Static Site Generation (SSG)
    95→
    96→The website uses React Router v7's pre-rendering feature to generate static HTML at build time.
    97→
    98→### How It Works
    99→
   100→1. **Build-time route discovery** (`src/prerender/`) fetches all projects and sessions from the API
   101→2. **React Router pre-renders** each route to static HTML + `.data` files
   102→3. **Output** is pure static files in `build/client/` - no server required for hosting
   103→
   104→### Build Requirements (SSG Only)
   105→
   106→SSG builds require API access for:
   107→1. **Route discovery** (`API_URI_BUILD`) - prerender function discovers all routes
   108→2. **Loader execution** (`API_URI_INTERNAL`) - loaders fetch data for each route
   109→
   110→```bash
   111→# SSG build against test server (handled by deploy-website-build.sh)
   112→SSG_BUILD=true \
   113→API_URI_BUILD=http://172.16.0.6/api/v1 \
   114→API_URI_INTERNAL=http://172.16.0.6/api/v1 \
   115→pnpm build
   116→```
   117→
   118→**Why two variables?**
   119→- `API_URI_BUILD` - Used by `src/prerender/` at config load time
   120→- `API_URI_INTERNAL` - Used by route loaders via `loadConfig()`
   121→
   122→For convenience, set both to the same value when building.
   123→
   124→### Pagination in Route Discovery
   125→
   126→The `prerenderApi.ts` uses `pageSize: 1000` when fetching projects and sessions to ensure all routes are discovered. The API defaults to 20 results per page, which would miss routes if not overridden.
   127→
   128→### Pre-rendered Routes
   129→
   130→| Route | Discovery |
   131→|-------|-----------|
   132→| `/`, `/about`, `/privacy-policy` | Static (automatic) |
   133→| `/projects` | Static (hardcoded) |
   134→| `/project/:projectId` | Dynamic (fetched from API) |
   135→| `/project/:projectId/session/:sessionId` | Dynamic (fetched from API) |
   136→
   137→### Build Output
   138→
   139→```
   140→build/client/
   141→├── index.html                    # / route
   142→├── about/index.html              # /about route
   143→├── privacy-policy/index.html     # /privacy-policy route
   144→├── projects/index.html           # /projects route
   145→├── project/
   146→│   └── {projectId}/
   147→│       ├── index.html            # /project/:projectId
   148→│       └── session/
   149→│           └── {sessionId}/
   150→│               └── index.html    # /project/:projectId/session/:sessionId
   151→└── assets/                       # JS, CSS bundles
   152→```
   153→
   154→### Deployment
   155→
   156→The `build/client/` directory contains all static files. Deploy to any static hosting:
   157→
   158→```bash
   159→# Cloudflare Pages (example)
   160→wrangler pages deploy build/client --project-name=codingwithclaude
   161→```
   162→
   163→---
   164→
   165→## Critical Naming Rules
   166→
   167→### 1. Avoid Plurals
   168→
   169→Use singular entity names for files and variables:
   170→
   171→```typescript
   172→// CORRECT
   173→project.ts
   174→codingSession.ts
   175→userProfile.ts
   176→
   177→// INCORRECT
   178→projects.ts
   179→codingSessions.ts
   180→userProfiles.ts
   181→```
   182→
   183→### 2. Consistent Entity Names
   184→
   185→Use the exact entity name from cwc-types throughout the codebase. No abbreviations, no variants:
   186→
   187→| Entity | Correct | Incorrect |
   188→|--------|---------|-----------|
   189→| CodingSession | `CodingSession`, `codingSession` | `session`, `code-session`, `codeSession`, `Session` |
   190→| Project | `Project`, `project` | `proj`, `prj` |
   191→| UserProfile | `UserProfile`, `userProfile` | `user`, `profile`, `User` |
   192→
   193→### 3. No Naming Variants
   194→
   195→Pick one form and use it everywhere:
   196→
   197→- **PascalCase** for React components and component folders
   198→- **camelCase** for non-component files and variables
   199→
   200→### 4. Qualified Component Names
   201→
   202→When components belong to a layout, prefix them with the layout name:
   203→
   204→```typescript
   205→// SiteLayout components
   206→SiteHeader.tsx
   207→SiteFooter.tsx
   208→SiteMenu.tsx
   209→
   210→// ProjectLayout components (future)
   211→ProjectHeader.tsx
   212→ProjectSidebar.tsx
   213→```
   214→
   215→---
   216→
   217→## Directory Structure
   218→
   219→```
   220→src/
   221→├── entry.client.tsx    # React Router v7 client entry (framework convention)
   222→├── entry.server.tsx    # React Router v7 SSR entry (framework convention)
   223→├── root.tsx            # HTML shell (framework convention)
   224→├── routes.ts           # Route configuration (framework convention)
   225→├── views/              # Page/view components (PascalCase folders)
   226→│   └── Home/
   227→│       ├── Home.tsx
   228→│       └── index.ts
   229→├── layouts/            # Layout templates with colocated SCSS
   230→│   └── SiteLayout/
   231→│       ├── SiteLayout.tsx
   232→│       ├── SiteHeader.tsx
   233→│       ├── SiteFooter.tsx
   234→│       ├── SiteMenu.tsx
   235→│       ├── index.ts
   236→│       └── styles/     # SCSS ported from html5up-phantom
   237→│           ├── main.scss
   238→│           ├── libs/
   239→│           ├── base/
   240→│           ├── components/
   241→│           └── layout/
   242→├── components/         # Shared/reusable components (flat for now)
   243→├── hooks/              # Global hooks
   244→│   ├── useMenu.tsx
   245→│   └── index.ts
   246→├── prerender/          # Build-time route discovery for SSG
   247→│   ├── prerender.ts    # Main route discovery function
   248→│   ├── prerenderApi.ts # Build-time API client
   249→│   └── index.ts        # Barrel export
   250→├── server/             # Server-only data fetching (by entity)
   251→│   ├── project.ts
   252→│   └── codingSession.ts
   253→└── config/
   254→    └── config.types.ts
   255→```
   256→
   257→### Framework Convention Files
   258→
   259→Files at `src/` root follow React Router v7 framework conventions and **cannot be renamed or relocated**:
   260→
   261→| File | Purpose |
   262→|------|---------|
   263→| `entry.client.tsx` | Client-side hydration entry point |
   264→| `entry.server.tsx` | SSR rendering entry point |
   265→| `root.tsx` | HTML shell (`<html>`, `<head>`, `<body>`) |
   266→| `routes.ts` | Route configuration |
   267→
   268→---
   269→
   270→## File Naming Conventions
   271→
   272→| File Type | Convention | Example |
   273→|-----------|------------|---------|
   274→| React component | PascalCase | `Home.tsx`, `SiteLayout.tsx` |
   275→| Component folder | PascalCase | `Home/`, `SiteLayout/` |
   276→| Hook | `use` + PascalCase, `.tsx` if renders UI | `useMenu.tsx` |
   277→| Server file | camelCase by entity | `project.ts`, `codingSession.ts` |
   278→| Config/utility | camelCase | `routes.ts`, `config.types.ts` |
   279→| SCSS partial | `_` prefix | `_vars.scss`, `_typography.scss` |
   280→| SCSS entry | `main.scss` | `main.scss` |
   281→| Barrel export | `index.ts` | `index.ts` |
   282→
   283→---
   284→
   285→## View Structure
   286→
   287→Each view folder contains:
   288→
   289→```
   290→views/Home/
   291→├── Home.tsx      # Main view component
   292→├── index.ts      # Barrel export
   293→└── [optional]    # View-specific components if needed
   294→```
   295→
   296→View-specific components live in the view folder, not in `components/`.
   297→
   298→---
   299→
   300→## Layout Structure
   301→
   302→Each layout folder contains components and colocated SCSS:
   303→
   304→```
   305→layouts/SiteLayout/
   306→├── SiteLayout.tsx      # Main layout wrapper (must have default export)
   307→├── SiteHeader.tsx      # Layout-specific component
   308→├── SiteFooter.tsx      # Layout-specific component
   309→├── SiteMenu.tsx        # Layout-specific component
   310→├── index.ts            # Barrel export
   311→└── styles/             # Colocated SCSS (ported from html5up-phantom)
   312→    ├── main.scss       # Entry point, imports all partials
   313→    ├── ATTRIBUTION.md  # CC BY 3.0 license attribution
   314→    ├── libs/           # Variables, functions, mixins, breakpoints
   315→    ├── base/           # Reset, page, typography
   316→    ├── components/     # Tiles, buttons, forms, etc.
   317→    └── layout/         # Header, menu, main, footer, wrapper
   318→```
   319→
   320→**CRITICAL: Route modules (including layouts) must have a default export** for React Router v7 to use them. Named exports alone will not work.
   321→
   322→---
   323→
   324→## Data Fetching
   325→
   326→### Loader Pattern (React Router v7)
   327→
   328→Data fetching happens in route loaders (server-side):
   329→
   330→```typescript
   331→// In routes.ts
   332→import { route } from '@react-router/dev/routes';
   333→
   334→export default [
   335→  route('project/:projectId', 'views/Project/Project.tsx'),
   336→];
   337→
   338→// In views/Project/Project.tsx
   339→import type { Route } from './+types/Project';
   340→
   341→export async function loader({ params }: Route.LoaderArgs) {
   342→  // Fetch from cwc-api
   343→  const project = await getProject(params.projectId);
   344→  return { project };
   345→}
   346→
   347→export default function Project({ loaderData }: Route.ComponentProps) {
   348→  const { project } = loaderData;
   349→  return <div>{project.name}</div>;
   350→}
   351→```
   352→
   353→### Server Files Organization
   354→
   355→Server files are organized by entity (singular):
   356→
   357→```
   358→server/
   359→├── project.ts        # getProject, getProjectList
   360→├── codingSession.ts  # getCodingSession, getCodingSessionContent
   361→└── index.ts          # Re-exports
   362→```
   363→
   364→---
   365→
   366→## Scripts
   367→
   368→```bash
   369→pnpm website dev       # Start dev server
   370→pnpm website build     # Production build
   371→pnpm website start     # Start production server
   372→pnpm website typecheck # Type check
   373→```
   374→
   375→---
   376→
   377→## Environment Variables
   378→
   379→| Variable | Description |
   380→|----------|-------------|
   381→| `APP_URL` | Public website URL |
   382→| `API_URI` | cwc-api service URL |
   383→| `CONTENT_URI` | cwc-content service URL |
   384→
   385→---
   386→
   387→## What to Check During Planning
   388→
   389→1. **Entity naming** - Using exact names from cwc-types?
   390→2. **File naming** - Following conventions (no plurals, correct case)?
   391→3. **Component location** - View-specific in views/, shared in components/?
   392→4. **SCSS location** - Colocated with layout?
   393→5. **Data fetching** - Using loader pattern?
   394→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

Edit

{
  "file_path": "/Users/jeffbazinet/cwc/source/coding-with-claude/packages/cwc-website/CLAUDE.md",
  "old_string": "### Pre-rendered Routes\n\n| Route | Discovery |\n|-------|-----------|\n| `/`, `/about`, `/privacy-policy` | Static (automatic) |\n| `/projects` | Static (hardcoded) |\n| `/project/:projectId` | Dynamic (fetched from API) |\n| `/project/:projectId/session/:sessionId` | Dynamic (fetched from API) |\n\n### Build Output\n\n```\nbuild/client/\n├── index.html                    # / route\n├── about/index.html              # /about route\n├── privacy-policy/index.html     # /privacy-policy route\n├── projects/index.html           # /projects route\n├── project/\n│   └── {projectId}/\n│       ├── index.html            # /project/:projectId\n│       └── session/\n│           └── {sessionId}/\n│               └── index.html    # /project/:projectId/session/:sessionId\n└── assets/                       # JS, CSS bundles\n```",
  "new_string": "### Pre-rendered Routes\n\n| Route | Discovery | View Type |\n|-------|-----------|-----------|\n| `/`, `/about`, `/privacy-policy` | Static (automatic) | SSG |\n| `/projects` | Static (hardcoded) | SSG |\n| `/project/:projectId` | Dynamic (fetched from API) | SSG |\n| `/session/:codingSessionPkId` | Dynamic (fetched from API) | SSG |\n| `/session/:codingSessionPkId/page/:pageNumber` | Dynamic (calculated) | SSG |\n| `/session-editor/:codingSessionPkId` | Not pre-rendered | Client-side |\n\n### Build Output\n\n```\nbuild/client/\n├── index.html                    # / route\n├── about/index.html              # /about route\n├── privacy-policy/index.html     # /privacy-policy route\n├── projects/index.html           # /projects route\n├── project/\n│   └── {projectId}/\n│       └── index.html            # /project/:projectId\n├── session/\n│   └── {codingSessionPkId}/\n│       ├── index.html            # /session/:codingSessionPkId\n│       └── page/\n│           └── {pageNumber}/\n│               └── index.html    # /session/:codingSessionPkId/page/:pageNumber\n└── assets/                       # JS, CSS bundles\n```"
}

Tool Result

The file /Users/jeffbazinet/cwc/source/coding-with-claude/packages/cwc-website/CLAUDE.md has been updated. Here's the result of running `cat -n` on a snippet of the edited file:
   124→### Pagination in Route Discovery
   125→
   126→The `prerenderApi.ts` uses `pageSize: 1000` when fetching projects and sessions to ensure all routes are discovered. The API defaults to 20 results per page, which would miss routes if not overridden.
   127→
   128→### Pre-rendered Routes
   129→
   130→| Route | Discovery | View Type |
   131→|-------|-----------|-----------|
   132→| `/`, `/about`, `/privacy-policy` | Static (automatic) | SSG |
   133→| `/projects` | Static (hardcoded) | SSG |
   134→| `/project/:projectId` | Dynamic (fetched from API) | SSG |
   135→| `/session/:codingSessionPkId` | Dynamic (fetched from API) | SSG |
   136→| `/session/:codingSessionPkId/page/:pageNumber` | Dynamic (calculated) | SSG |
   137→| `/session-editor/:codingSessionPkId` | Not pre-rendered | Client-side |
   138→
   139→### Build Output
   140→
   141→```
   142→build/client/
   143→├── index.html                    # / route
   144→├── about/index.html              # /about route
   145→├── privacy-policy/index.html     # /privacy-policy route
   146→├── projects/index.html           # /projects route
   147→├── project/
   148→│   └── {projectId}/
   149→│       └── index.html            # /project/:projectId
   150→├── session/
   151→│   └── {codingSessionPkId}/
   152→│       ├── index.html            # /session/:codingSessionPkId
   153→│       └── page/
   154→│           └── {pageNumber}/
   155→│               └── index.html    # /session/:codingSessionPkId/page/:pageNumber
   156→└── assets/                       # JS, CSS bundles
   157→```
   158→
   159→### Deployment
   160→
   161→The `build/client/` directory contains all static files. Deploy to any static hosting:

Tool Result

The file /Users/jeffbazinet/cwc/source/coding-with-claude/packages/cwc-website/CLAUDE.md has been updated. Here's the result of running `cat -n` on a snippet of the edited file:
   166→```
   167→
   168→---
   169→
   170→## URL Architecture (Session 045)
   171→
   172→### Simplified Session URLs
   173→
   174→Session URLs use `codingSessionPkId` (integer primary key) instead of the verbose UUID-based paths:
   175→
   176→| Old URL | New URL |
   177→|---------|---------|
   178→| `/project/myapp/session/7e6a848a-f0e0-4a10-83e0-495e287003f8` | `/session/42` |
   179→| `/project/myapp/session/7e6a848a-.../page/2` | `/session/42/page/2` |
   180→| `/project/myapp/session/7e6a848a-.../edit` | `/session-editor/42` |
   181→
   182→**Rationale:**
   183→- **Cleaner URLs:** `/session/42` is more readable and shareable
   184→- **No redundancy:** Project info is derived from `session.projectPkId` - no need in URL
   185→- **Globally unique:** `codingSessionPkId` is unique across all projects
   186→- **Consistent identifiers:** All session operations use `codingSessionPkId`
   187→
   188→### SSG vs Client-Side Views
   189→
   190→The website uses two types of views:
   191→
   192→| View Type | Auth Required | Pre-rendered | Example |
   193→|-----------|---------------|--------------|---------|
   194→| **SSG (Server)** | No | Yes | `/session/42`, `/project/myapp` |
   195→| **Client-Side** | Yes | No | `/session-editor/42` |
   196→
   197→**SSG Views** (`views/server/`):
   198→- Pre-rendered at build time to static HTML
   199→- Loader fetches data during build
   200→- Public content, no authentication
   201→- Located in `views/server/` directory
   202→
   203→**Client-Side Views** (`views/client/`):
   204→- Rendered in browser after page load
   205→- Fetches data via `clientApi` after mount
   206→- Requires user authentication
   207→- Located in `views/client/` directory
   208→
   209→### Project Context Derivation
   210→
   211→When loading `/session/42`:
   212→1. Fetch session by `codingSessionPkId = 42`
   213→2. Extract `projectPkId` from session response
   214→3. Fetch project using `getProjectByPkId(session.projectPkId)`
   215→4. No `projectId` needed in URL
   216→
   217→---
   218→
   219→## Critical Naming Rules
   220→
   221→### 1. Avoid Plurals
   222→
   223→Use singular entity names for files and variables:

Let me also check if cwc-api CLAUDE.md needs any updates regarding the codingSessionPkId change:

Good - cwc-api CLAUDE.md focuses on architecture patterns, not specific payload types. The documentation updates are complete.

Final Summary - Session 045

Documentation Updated

cwc-website/CLAUDE.md:

Added new "URL Architecture (Session 045)" section documenting:
- Simplified session URLs (/session/42 instead of /project/myapp/session/uuid)
- SSG vs Client-Side view patterns
- Project context derivation from session's projectPkId
Updated "Pre-rendered Routes" table with new URL patterns
Updated "Build Output" section with new directory structure

cwc-backend-utils/CLAUDE.md:

Rewrote "CORS Configuration" section:
- Express handles CORS exclusively (not nginx)
- Documented as deliberate architectural decision
- Added critical warning about duplicate headers
- Updated devCorsOrigin port documentation (5173 for Vite)
- Added troubleshooting section

cwc-deployment/CLAUDE.md:

Updated nginx routes section (removed CORS references)
Added explicit statement that nginx does NOT handle CORS

Code Changes

File	Change
`cwc-backend-utils/src/express/service.ts`	Re-enabled CORS middleware
`cwc-backend-utils/src/express/cors.ts`	Restored implementation
`cwc-deployment/.../default.conf.test.template`	Removed CORS headers
`cwc-deployment/.../default.conf.prod.template`	Removed CORS headers
`cwc-configuration-helper/src/configuration.ts`	Fixed devCorsOrigin port: 3000 → 5173

Key Decisions

URL Simplification: /session/{codingSessionPkId} instead of /project/{projectId}/session/{sessionId}
CORS Architecture: Express middleware handles CORS, nginx is just a proxy
View Organization: SSG views in views/server/, client-side views in views/client/

Session 45: website improvements

55 files modified

packages/cwc-api/src/apis/CwcApiV1/queries/codingSession/getCodingSession.ts

2 versions

Version 1

'use strict';

import type { SqlClientType } from 'cwc-backend-utils';
import type { CwcCodingSession } from 'cwc-types';
import type { RequestContext } from '../../../../context';
import type { OperationResult } from '../../../../handlers/handler.types';
import type { OperationAccessPayload } from '../../../../policies/policy.types';
import type { GetCodingSessionPayload } from '../../types';
import { checkOperationAccess } from '../../../../policies';
import { accessPolicies } from '../../accessPolicies';
import { selectCodingSession } from '../../../../sql/codingSession';

/**
 * Options for getCodingSession operation
 */
type GetCodingSessionOptions = {
  sqlClient: SqlClientType;
  payload: GetCodingSessionPayload;
  requestContext: RequestContext;
};

/**
 * Get a single coding session by sessionId
 *
 * Note: Only published sessions are accessible to non-owners
 */
export async function getCodingSession({
  sqlClient,
  payload,
  requestContext,
}: GetCodingSessionOptions): Promise<OperationResult<CwcCodingSession>> {
  const accessResult = await checkOperationAccess({
    sqlClient,
    requestContext,
    payload: payload as OperationAccessPayload,
    requiredRole: accessPolicies.codingSession.get,
  });

  if (!accessResult.allowed) {
    return {
      success: false,
      errorCode: accessResult.errorCode ?? 'UNAUTHORIZED',
      errorMessage: accessResult.reason ?? 'Access denied',
    };
  }

  // 2. Validate required fields
  if (!payload.sessionId) {
    return {
      success: false,
      errorCode: 'VALIDATION_ERROR',
      errorMessage: 'sessionId is required',
    };
  }

  // Execute SQL function
  const result = await selectCodingSessionById(
    sqlClient,
    { sessionId: payload.sessionId },
    requestContext.userPkId
  );

  if (!result.success) {
    return {
      success: false,
      errorCode: 'NOT_FOUND',
      errorMessage: 'Coding session not found',
    };
  }

  // For non-authenticated users, only return published sessions
  // Owners can view unpublished sessions
  if (!result.data.published) {
    // Check if user is the owner
    const isOwner =
      requestContext.isAuthenticated &&
      requestContext.ownedProjects.includes(result.data.projectPkId.toString());

    // If not owner and not published, return not found
    // Note: We need to check ownership via projectId, not projectPkId
    // This requires an additional lookup or we trust the data
    if (!isOwner && !requestContext.isAuthenticated) {
      return {
        success: false,
        errorCode: 'NOT_FOUND',
        errorMessage: 'Coding session not found',
      };
    }
  }

  return { success: true, data: result.data };
}

Version 2 (latest)

'use strict';

import type { SqlClientType } from 'cwc-backend-utils';
import type { CwcCodingSession } from 'cwc-types';
import type { RequestContext } from '../../../../context';
import type { OperationResult } from '../../../../handlers/handler.types';
import type { OperationAccessPayload } from '../../../../policies/policy.types';
import type { GetCodingSessionPayload } from '../../types';
import { checkOperationAccess } from '../../../../policies';
import { accessPolicies } from '../../accessPolicies';
import { selectCodingSession } from '../../../../sql/codingSession';

/**
 * Options for getCodingSession operation
 */
type GetCodingSessionOptions = {
  sqlClient: SqlClientType;
  payload: GetCodingSessionPayload;
  requestContext: RequestContext;
};

/**
 * Get a single coding session by sessionId
 *
 * Note: Only published sessions are accessible to non-owners
 */
export async function getCodingSession({
  sqlClient,
  payload,
  requestContext,
}: GetCodingSessionOptions): Promise<OperationResult<CwcCodingSession>> {
  const accessResult = await checkOperationAccess({
    sqlClient,
    requestContext,
    payload: payload as OperationAccessPayload,
    requiredRole: accessPolicies.codingSession.get,
  });

  if (!accessResult.allowed) {
    return {
      success: false,
      errorCode: accessResult.errorCode ?? 'UNAUTHORIZED',
      errorMessage: accessResult.reason ?? 'Access denied',
    };
  }

  // Validate required fields
  if (!payload.codingSessionPkId) {
    return {
      success: false,
      errorCode: 'VALIDATION_ERROR',
      errorMessage: 'codingSessionPkId is required',
    };
  }

  // Execute SQL function
  const result = await selectCodingSession(
    sqlClient,
    { codingSessionPkId: payload.codingSessionPkId },
    requestContext.userPkId
  );

  if (!result.success) {
    return {
      success: false,
      errorCode: 'NOT_FOUND',
      errorMessage: 'Coding session not found',
    };
  }

  // For non-authenticated users, only return published sessions
  // Owners can view unpublished sessions
  if (!result.data.published) {
    // Check if user is the owner
    const isOwner =
      requestContext.isAuthenticated &&
      requestContext.ownedProjects.includes(result.data.projectPkId.toString());

    // If not owner and not published, return not found
    // Note: We need to check ownership via projectId, not projectPkId
    // This requires an additional lookup or we trust the data
    if (!isOwner && !requestContext.isAuthenticated) {
      return {
        success: false,
        errorCode: 'NOT_FOUND',
        errorMessage: 'Coding session not found',
      };
    }
  }

  return { success: true, data: result.data };
}

packages/cwc-api/src/apis/CwcApiV1/queries/project/getProject.ts

2 versions

Version 1

'use strict';

import type { SqlClientType } from 'cwc-backend-utils';
import type { CwcProject } from 'cwc-types';
import type { RequestContext } from '../../../../context';
import type { OperationResult } from '../../../../handlers/handler.types';
import type { OperationAccessPayload } from '../../../../policies/policy.types';
import type { GetProjectPayload } from '../../types';
import { checkOperationAccess } from '../../../../policies';
import { accessPolicies } from '../../accessPolicies';
import { selectProject, selectProjectById } from '../../../../sql/project';

/**
 * Options for getProject operation
 */
type GetProjectOptions = {
  sqlClient: SqlClientType;
  payload: GetProjectPayload;
  requestContext: RequestContext;
};

/**
 * Get a single project by projectId
 */
export async function getProject({
  sqlClient,
  payload,
  requestContext,
}: GetProjectOptions): Promise<OperationResult<CwcProject>> {
  const accessResult = await checkOperationAccess({
    sqlClient,
    requestContext,
    payload: payload as OperationAccessPayload,
    requiredRole: accessPolicies.project.get,
  });

  if (!accessResult.allowed) {
    return {
      success: false,
      errorCode: accessResult.errorCode ?? 'UNAUTHORIZED',
      errorMessage: accessResult.reason ?? 'Access denied',
    };
  }

  if (!payload.projectId) {
    return {
      success: false,
      errorCode: 'VALIDATION_ERROR',
      errorMessage: 'projectId is required',
    };
  }

  const result = await selectProjectById(
    sqlClient,
    { projectId: payload.projectId },
    requestContext.userPkId
  );

  if (!result.success) {
    return {
      success: false,
      errorCode: 'NOT_FOUND',
      errorMessage: 'Project not found',
    };
  }

  return { success: true, data: result.data };
}

Version 2 (latest)

'use strict';

import type { SqlClientType } from 'cwc-backend-utils';
import type { CwcProject } from 'cwc-types';
import type { RequestContext } from '../../../../context';
import type { OperationResult } from '../../../../handlers/handler.types';
import type { OperationAccessPayload } from '../../../../policies/policy.types';
import type { GetProjectPayload } from '../../types';
import { checkOperationAccess } from '../../../../policies';
import { accessPolicies } from '../../accessPolicies';
import { selectProject, selectProjectById } from '../../../../sql/project';

/**
 * Options for getProject operation
 */
type GetProjectOptions = {
  sqlClient: SqlClientType;
  payload: GetProjectPayload;
  requestContext: RequestContext;
};

/**
 * Get a single project by projectId or projectPkId
 *
 * Supports lookup by either:
 * - projectId (string natural key)
 * - projectPkId (integer primary key)
 */
export async function getProject({
  sqlClient,
  payload,
  requestContext,
}: GetProjectOptions): Promise<OperationResult<CwcProject>> {
  const accessResult = await checkOperationAccess({
    sqlClient,
    requestContext,
    payload: payload as OperationAccessPayload,
    requiredRole: accessPolicies.project.get,
  });

  if (!accessResult.allowed) {
    return {
      success: false,
      errorCode: accessResult.errorCode ?? 'UNAUTHORIZED',
      errorMessage: accessResult.reason ?? 'Access denied',
    };
  }

  // Validate required fields - must provide either projectPkId or projectId
  const hasProjectPkId = 'projectPkId' in payload && payload.projectPkId !== undefined;
  const hasProjectId = 'projectId' in payload && payload.projectId !== undefined;

  if (!hasProjectPkId && !hasProjectId) {
    return {
      success: false,
      errorCode: 'VALIDATION_ERROR',
      errorMessage: 'projectPkId or projectId is required',
    };
  }

  // Execute SQL function based on which identifier was provided
  const result = hasProjectPkId
    ? await selectProject(
        sqlClient,
        { projectPkId: (payload as { projectPkId: number }).projectPkId },
        requestContext.userPkId
      )
    : await selectProjectById(
        sqlClient,
        { projectId: (payload as { projectId: string }).projectId },
        requestContext.userPkId
      );

  if (!result.success) {
    return {
      success: false,
      errorCode: 'NOT_FOUND',
      errorMessage: 'Project not found',
    };
  }

  return { success: true, data: result.data };
}

packages/cwc-api/src/apis/CwcApiV1/types.ts

2 versions

Version 1

'use strict';

import type {
  CwcProjectType,
  CwcCodingSessionAttachmentMimeType,
  CwcCommentEntityType,
  CwcReactionEntityType,
  CwcReactionName,
  CwcContentReportEntityType,
  CwcContentReportStatus,
  CwcAbuseReportStatus,
} from 'cwc-types';

// ============================================================================
// Pagination Types
// ============================================================================

/**
 * Standard pagination parameters for list operations
 */
export type PaginationParams = {
  page?: number; // 1-based, defaults to 1
  pageSize?: number; // Defaults to 20, max 100
};

// ============================================================================
// Project Payloads
// ============================================================================

export type GetProjectPayload = {
  projectId: string;
};

export type ListProjectPayload = PaginationParams & {
  userPkId?: number; // Filter by owner
};

export type CreateProjectPayload = {
  projectId: string;
  projectSessionFolder: string;
  projectType: CwcProjectType;
  sensitiveStrings?: string[]; // Array of regex patterns to search for
};

export type UpdateProjectPayload = {
  projectPkId: number;
  projectId?: string;
  projectSessionFolder?: string;
  projectType?: CwcProjectType;
  sensitiveStrings?: string[]; // Array of regex patterns to search for
};

export type DeleteProjectPayload = {
  projectPkId: number;
};

// ============================================================================
// Coding Session Payloads
// ============================================================================

export type GetCodingSessionPayload = {
  codingSessionPkId: number;
};

export type ListCodingSessionPayload = PaginationParams & {
  projectPkId?: number;
  userPkId?: number;
  published?: boolean; // Filter by published status
};

export type CreateCodingSessionPayload = {
  projectPkId: number;
  description: string;
  published: boolean;
  sessionId: string;
  storageKey: string;
  startTimestamp: string;
  endTimestamp: string;
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};

export type UpdateCodingSessionPayload = {
  codingSessionPkId: number;
  description?: string;
  published?: boolean;
  startTimestamp?: string;
  endTimestamp?: string;
  gitBranch?: string;
  model?: string;
  messageCount?: number;
  filesModifiedCount?: number;
};

export type DeleteCodingSessionPayload = {
  codingSessionPkId: number;
};

// ============================================================================
// Coding Session Note Payloads
// ============================================================================

export type GetCodingSessionNotePayload = {
  codingSessionNotePkId: number;
};

export type ListCodingSessionNotePayload = PaginationParams & {
  codingSessionPkId: number;
  messageUuid?: string;
};

export type CreateCodingSessionNotePayload = {
  codingSessionPkId: number;
  messageUuid: string;
  noteText: string;
};

export type UpdateCodingSessionNotePayload = {
  codingSessionNotePkId: number;
  noteText?: string;
};

export type DeleteCodingSessionNotePayload = {
  codingSessionNotePkId: number;
};

// ============================================================================
// Coding Session Attachment Payloads
// ============================================================================

export type GetCodingSessionAttachmentPayload = {
  codingSessionAttachmentPkId: number;
};

export type ListCodingSessionAttachmentPayload = PaginationParams & {
  codingSessionPkId: number;
};

export type CreateCodingSessionAttachmentPayload = {
  projectPkId: number;
  codingSessionPkId: number;
  messageUuid?: string;
  filename: string;
  mimeType: CwcCodingSessionAttachmentMimeType;
  height: number;
  width: number;
};

export type UpdateCodingSessionAttachmentPayload = {
  codingSessionAttachmentPkId: number;
  messageUuid?: string;
  filename?: string;
  height?: number;
  width?: number;
};

export type DeleteCodingSessionAttachmentPayload = {
  codingSessionAttachmentPkId: number;
};

// ============================================================================
// Comment Payloads
// ============================================================================

export type GetCommentPayload = {
  commentPkId: number;
};

export type ListCommentPayload = PaginationParams & {
  entityPkId: number;
  entityType: CwcCommentEntityType;
};

export type CreateCommentPayload = {
  projectPkId: number;
  entityPkId: number;
  entityType: CwcCommentEntityType;
  text: string;
};

export type UpdateCommentPayload = {
  commentPkId: number;
  text: string;
};

export type DeleteCommentPayload = {
  commentPkId: number;
};

// ============================================================================
// Reaction Payloads
// ============================================================================

export type GetReactionPayload = {
  reactionPkId: number;
};

export type ListReactionPayload = PaginationParams & {
  entityPkId: number;
  entityType: CwcReactionEntityType;
};

export type CreateReactionPayload = {
  projectPkId: number;
  entityPkId: number;
  entityType: CwcReactionEntityType;
  reactionName: CwcReactionName;
};

// No UpdateReactionPayload - reactions are immutable

export type DeleteReactionPayload = {
  reactionPkId: number;
};

// ============================================================================
// Content Report Payloads
// ============================================================================

export type GetContentReportPayload = {
  contentReportPkId: number;
};

export type ListContentReportPayload = PaginationParams & {
  userPkId?: number; // Filter by reporter (for viewing own reports)
  entityPkId?: number;
  entityType?: CwcContentReportEntityType;
  status?: CwcContentReportStatus;
};

export type CreateContentReportPayload = {
  projectPkId: number;
  entityPkId: number;
  entityType: CwcContentReportEntityType;
  message: string;
};

export type UpdateContentReportPayload = {
  contentReportPkId: number;
  status: CwcContentReportStatus; // Only status can be updated
};

// No DeleteContentReportPayload - reports cannot be deleted by users

// ============================================================================
// Abuse Report Payloads
// ============================================================================

export type GetAbuseReportPayload = {
  abuseReportPkId: number;
};

export type ListAbuseReportPayload = PaginationParams & {
  userPkId?: number; // Filter by reporter (for viewing own reports)
  status?: CwcAbuseReportStatus;
};

export type CreateAbuseReportPayload = {
  projectPkId: number;
  usernames: string;
  message: string;
};

export type UpdateAbuseReportPayload = {
  abuseReportPkId: number;
  status: CwcAbuseReportStatus; // Only status can be updated
};

// No DeleteAbuseReportPayload - reports cannot be deleted by users

// ============================================================================
// User Payloads
// ============================================================================

export type GetUserPayload = {
  userPkId: number;
};

Version 2 (latest)

'use strict';

import type {
  CwcProjectType,
  CwcCodingSessionAttachmentMimeType,
  CwcCommentEntityType,
  CwcReactionEntityType,
  CwcReactionName,
  CwcContentReportEntityType,
  CwcContentReportStatus,
  CwcAbuseReportStatus,
} from 'cwc-types';

// ============================================================================
// Pagination Types
// ============================================================================

/**
 * Standard pagination parameters for list operations
 */
export type PaginationParams = {
  page?: number; // 1-based, defaults to 1
  pageSize?: number; // Defaults to 20, max 100
};

// ============================================================================
// Project Payloads
// ============================================================================

export type GetProjectPayload =
  | { projectId: string }
  | { projectPkId: number };

export type ListProjectPayload = PaginationParams & {
  userPkId?: number; // Filter by owner
};

export type CreateProjectPayload = {
  projectId: string;
  projectSessionFolder: string;
  projectType: CwcProjectType;
  sensitiveStrings?: string[]; // Array of regex patterns to search for
};

export type UpdateProjectPayload = {
  projectPkId: number;
  projectId?: string;
  projectSessionFolder?: string;
  projectType?: CwcProjectType;
  sensitiveStrings?: string[]; // Array of regex patterns to search for
};

export type DeleteProjectPayload = {
  projectPkId: number;
};

// ============================================================================
// Coding Session Payloads
// ============================================================================

export type GetCodingSessionPayload = {
  codingSessionPkId: number;
};

export type ListCodingSessionPayload = PaginationParams & {
  projectPkId?: number;
  userPkId?: number;
  published?: boolean; // Filter by published status
};

export type CreateCodingSessionPayload = {
  projectPkId: number;
  description: string;
  published: boolean;
  sessionId: string;
  storageKey: string;
  startTimestamp: string;
  endTimestamp: string;
  gitBranch: string;
  model: string;
  messageCount: number;
  filesModifiedCount: number;
};

export type UpdateCodingSessionPayload = {
  codingSessionPkId: number;
  description?: string;
  published?: boolean;
  startTimestamp?: string;
  endTimestamp?: string;
  gitBranch?: string;
  model?: string;
  messageCount?: number;
  filesModifiedCount?: number;
};

export type DeleteCodingSessionPayload = {
  codingSessionPkId: number;
};

// ============================================================================
// Coding Session Note Payloads
// ============================================================================

export type GetCodingSessionNotePayload = {
  codingSessionNotePkId: number;
};

export type ListCodingSessionNotePayload = PaginationParams & {
  codingSessionPkId: number;
  messageUuid?: string;
};

export type CreateCodingSessionNotePayload = {
  codingSessionPkId: number;
  messageUuid: string;
  noteText: string;
};

export type UpdateCodingSessionNotePayload = {
  codingSessionNotePkId: number;
  noteText?: string;
};

export type DeleteCodingSessionNotePayload = {
  codingSessionNotePkId: number;
};

// ============================================================================
// Coding Session Attachment Payloads
// ============================================================================

export type GetCodingSessionAttachmentPayload = {
  codingSessionAttachmentPkId: number;
};

export type ListCodingSessionAttachmentPayload = PaginationParams & {
  codingSessionPkId: number;
};

export type CreateCodingSessionAttachmentPayload = {
  projectPkId: number;
  codingSessionPkId: number;
  messageUuid?: string;
  filename: string;
  mimeType: CwcCodingSessionAttachmentMimeType;
  height: number;
  width: number;
};

export type UpdateCodingSessionAttachmentPayload = {
  codingSessionAttachmentPkId: number;
  messageUuid?: string;
  filename?: string;
  height?: number;
  width?: number;
};

export type DeleteCodingSessionAttachmentPayload = {
  codingSessionAttachmentPkId: number;
};

// ============================================================================
// Comment Payloads
// ============================================================================

export type GetCommentPayload = {
  commentPkId: number;
};

export type ListCommentPayload = PaginationParams & {
  entityPkId: number;
  entityType: CwcCommentEntityType;
};

export type CreateCommentPayload = {
  projectPkId: number;
  entityPkId: number;
  entityType: CwcCommentEntityType;
  text: string;
};

export type UpdateCommentPayload = {
  commentPkId: number;
  text: string;
};

export type DeleteCommentPayload = {
  commentPkId: number;
};

// ============================================================================
// Reaction Payloads
// ============================================================================

export type GetReactionPayload = {
  reactionPkId: number;
};

export type ListReactionPayload = PaginationParams & {
  entityPkId: number;
  entityType: CwcReactionEntityType;
};

export type CreateReactionPayload = {
  projectPkId: number;
  entityPkId: number;
  entityType: CwcReactionEntityType;
  reactionName: CwcReactionName;
};

// No UpdateReactionPayload - reactions are immutable

export type DeleteReactionPayload = {
  reactionPkId: number;
};

// ============================================================================
// Content Report Payloads
// ============================================================================

export type GetContentReportPayload = {
  contentReportPkId: number;
};

export type ListContentReportPayload = PaginationParams & {
  userPkId?: number; // Filter by reporter (for viewing own reports)
  entityPkId?: number;
  entityType?: CwcContentReportEntityType;
  status?: CwcContentReportStatus;
};

export type CreateContentReportPayload = {
  projectPkId: number;
  entityPkId: number;
  entityType: CwcContentReportEntityType;
  message: string;
};

export type UpdateContentReportPayload = {
  contentReportPkId: number;
  status: CwcContentReportStatus; // Only status can be updated
};

// No DeleteContentReportPayload - reports cannot be deleted by users

// ============================================================================
// Abuse Report Payloads
// ============================================================================

export type GetAbuseReportPayload = {
  abuseReportPkId: number;
};

export type ListAbuseReportPayload = PaginationParams & {
  userPkId?: number; // Filter by reporter (for viewing own reports)
  status?: CwcAbuseReportStatus;
};

export type CreateAbuseReportPayload = {
  projectPkId: number;
  usernames: string;
  message: string;
};

export type UpdateAbuseReportPayload = {
  abuseReportPkId: number;
  status: CwcAbuseReportStatus; // Only status can be updated
};

// No DeleteAbuseReportPayload - reports cannot be deleted by users

// ============================================================================
// User Payloads
// ============================================================================

export type GetUserPayload = {
  userPkId: number;
};

packages/cwc-backend-utils/CLAUDE.md

cwc-backend-utils Package

Backend utilities for CWC microservices. Node.js-specific utilities only.

Critical Architecture Rule

Only cwc-sql Talks to Database:

✅ All backend services MUST use SqlClient HTTP client
✅ All database operations flow through cwc-sql service via POST /data/v1/command
❌ NEVER import MariaDB or execute SQL from other packages

AuthClient - cwc-auth HTTP Client

Location: src/AuthClient/

HTTP client for cwc-auth service, following same pattern as SqlClient.

Purpose:

Provides typed interface for cwc-auth endpoints (/verify-token, /renew-session, /logon)
Enables services to verify JWTs without duplicating auth logic
Enables CLI tools to login and obtain JWTs
Returns typed Result objects for easy error handling

Configuration:

type AuthClientConfig = {
  authUriInternal: string; // e.g., 'http://cwc-auth:5005/auth/v1' (Docker)
  authUriExternal?: string; // e.g., 'http://localhost:5005/auth/v1' (external callers)
  timeout?: number; // Default: 5000ms (10000ms for login)
};

URI Selection: If authUriExternal is provided, it takes precedence over authUriInternal. This allows internal services (cwc-api, cwc-content) to use Docker DNS while external callers (CLI tools) use external URLs.

Usage - Token Verification (Services):

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUriInternal: config.authUriInternal },
  logger: logger,
  clientName: 'cwc-api',
});

const result = await authClient.verifyToken(authHeader);
if (result.success) {
  // result.payload contains UserJwtPayload
} else {
  // result.error contains error code
}

Usage - Login (CLI Tools):

import { AuthClient } from 'cwc-backend-utils';

const authClient = new AuthClient({
  config: { authUriInternal: '', authUriExternal: config.authUriExternal },
  logger: undefined,
  clientName: 'cwc-session-importer',
});

const loginResult = await authClient.login(username, password);
if (loginResult.success) {
  // loginResult.jwt contains the JWT token
} else {
  // loginResult.error contains error code
  // loginResult.errorMessage contains optional detail (dev mode only)
}

Error Handling:

Missing token → { success: false, error: 'MISSING_TOKEN' }
Invalid/expired token (401) → { success: false, error: 'INVALID_TOKEN' } or specific errorCode
Login failed (401) → { success: false, error: 'INVALID_CREDENTIALS' } or specific errorCode
Network/timeout errors → { success: false, error: 'AUTH_SERVICE_ERROR' } + logs error

Design Pattern:

Similar to SqlClient: config + logger + clientName
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts), not auth failures

StorageClient - cwc-storage HTTP Client

Location: src/StorageClient/

HTTP client for cwc-storage service, following same pattern as AuthClient.

Purpose:

Provides typed interface for cwc-storage file operations
Handles GET, PUT, DELETE operations for session data files
Returns typed Result objects for easy error handling

Configuration:

type StorageClientConfig = {
  storageUri: string; // e.g., 'http://localhost:5030/storage/v1'
  storageApiKey: string; // API key for x-api-key header
  timeout?: number; // Default: 30000ms (GET/DELETE), 60000ms (PUT)
};

Usage:

import { StorageClient } from 'cwc-backend-utils';

const storageClient = new StorageClient({
  config: {
    storageUri: config.storageUri,
    storageApiKey: config.secrets.storageApiKey,
  },
  logger: logger,
  clientName: 'cwc-content',
});

// Get file
const getResult = await storageClient.getFile(projectId, filename);
if (getResult.success) {
  // getResult.data is Buffer
} else {
  // getResult.error is error code
}

// Put file
const putResult = await storageClient.putFile(projectId, filename, base64Data);
if (putResult.success) {
  // putResult.filename is the stored filename
}

// Delete file
const deleteResult = await storageClient.deleteFile(projectId, filename);

Error Handling:

File not found (400) → { success: false, error: 'FILE_NOT_FOUND' }
Unauthorized (401) → { success: false, error: 'UNAUTHORIZED' }
Network/timeout errors → { success: false, error: 'STORAGE_SERVICE_ERROR' } + logs error
Write failed → { success: false, error: 'STORAGE_WRITE_FAILED' }
Delete failed → { success: false, error: 'STORAGE_DELETE_FAILED' }

Design Pattern:

Same as AuthClient: config + logger + clientName
Uses x-api-key header for authentication (matching cwc-storage)
Graceful degradation: errors don't throw, return typed failure result
Logging: Only logs unexpected errors (network issues, timeouts)

ApiClient - cwc-api HTTP Client

Location: src/ApiClient/

HTTP client for cwc-api service, following same pattern as AuthClient.

Purpose:

Provides typed interface for cwc-api CRUD operations
Handles project and codingSession operations
Uses JWT authentication (Bearer token)
Returns typed Result objects for easy error handling

Configuration:

type ApiClientConfig = {
  apiUri: string; // e.g., 'http://localhost:5040/api/v1'
  timeout?: number; // Default: 30000ms
};

type ApiClientOptions = {
  config: ApiClientConfig;
  jwt: string; // Bearer token for authentication
  logger: ILogger | undefined;
  clientName: string;
};

Usage:

import { ApiClient } from 'cwc-backend-utils';

const apiClient = new ApiClient({
  config: { apiUri: config.apiUri },
  jwt: userJwt,
  logger: logger,
  clientName: 'cwc-session-importer',
});

// Get project by natural key
const projectResult = await apiClient.getProject('coding-with-claude');
if (projectResult.success) {
  // projectResult.data is CwcProject
}

// List coding sessions for a project
const listResult = await apiClient.listCodingSessions(projectPkId);

// Create a coding session
const createResult = await apiClient.createCodingSession({
  projectPkId,
  sessionId,
  description,
  published: false,
  storageKey,
  startTimestamp,
  endTimestamp,
  gitBranch,
  model,
  messageCount,
  filesModifiedCount,
});

// Delete a coding session
const deleteResult = await apiClient.deleteCodingSession(codingSessionPkId);

Error Handling:

Unauthorized (401) → { success: false, error: 'UNAUTHORIZED' }
Forbidden (403) → { success: false, error: 'FORBIDDEN' }
Not found (404) → { success: false, error: 'NOT_FOUND' }
Network/timeout errors → { success: false, error: 'API_SERVICE_ERROR' } + logs error

Design Pattern:

Same as AuthClient: config + jwt + logger + clientName
Uses Authorization: Bearer header for authentication
Auto-updates JWT on renewal (when API returns new JWT)
Graceful degradation: errors don't throw, return typed failure result

ContentClient - cwc-content HTTP Client

Location: src/ContentClient/

HTTP client for cwc-content service, following same pattern as ApiClient.

Purpose:

Provides typed interface for cwc-content file operations
Handles GET, PUT, DELETE for session data files
Automatically gzips and base64-encodes data on PUT
Uses JWT authentication (Bearer token)

Configuration:

type ContentClientConfig = {
  contentUri: string; // e.g., 'http://localhost:5008/content/v1'
  timeout?: number; // Default: 60000ms
};

type ContentClientOptions = {
  config: ContentClientConfig;
  jwt: string; // Bearer token for authentication
  logger: ILogger | undefined;
  clientName: string;
};

Usage:

import { ContentClient } from 'cwc-backend-utils';

const contentClient = new ContentClient({
  config: { contentUri: config.contentUri },
  jwt: userJwt,
  logger: logger,
  clientName: 'cwc-session-importer',
});

// Generate storage filename
const filename = ContentClient.generateStorageFilename(sessionId, startTimestamp);
// Returns: '2025-01-15_10-30-00_abc123.json.gz'

// Upload session data (auto-gzips and base64-encodes)
const putResult = await contentClient.putSessionData(projectId, filename, sessionData);
if (putResult.success) {
  // putResult.filename is the stored filename
}

// Delete session data
const deleteResult = await contentClient.deleteSessionData(projectId, filename);

// Get session data
const getResult = await contentClient.getSessionData(projectId, filename);
if (getResult.success) {
  // getResult.data is Buffer
}

Error Handling:

Unauthorized (401) → { success: false, error: 'UNAUTHORIZED' }
Forbidden (403) → { success: false, error: 'FORBIDDEN' }
Not found (404) → { success: false, error: 'NOT_FOUND' }
Network/timeout errors → { success: false, error: 'CONTENT_SERVICE_ERROR' } + logs error

Design Pattern:

Same as ApiClient: config + jwt + logger + clientName
Uses Authorization: Bearer header for authentication
Static helper generateStorageFilename() for consistent naming
Graceful degradation: errors don't throw, return typed failure result

JWT Syncing Between Clients - CRITICAL

When using multiple HTTP clients that share a JWT, you MUST sync the JWT after any call that might trigger renewal.

cwc-api renews the user's session on every authenticated request (except auth errors). The renewed JWT is returned in the response. If you're using multiple clients (e.g., ApiClient + ContentClient), you must sync the JWT between them:

// Initialize both clients with the same JWT
const apiClient = new ApiClient({ config, jwt, logger, clientName });
const contentClient = new ContentClient({ config, jwt, logger, clientName });

// Call API (might renew the JWT)
const result = await apiClient.getProject(projectId);

// CRITICAL: Sync JWT to ContentClient before using it
contentClient.setJwt(apiClient.getJwt());

// Now ContentClient has the renewed JWT
await contentClient.putSessionData(projectId, filename, data);

Why this matters: When cwc-api renews a session, it deletes the old JWT from the database (SESSION_REVOKED). If ContentClient still has the old JWT, cwc-auth will reject it as revoked.

Available methods:

apiClient.getJwt() - Get current JWT (may have been renewed)
contentClient.setJwt(jwt) - Update JWT for subsequent requests

JWT Authentication - CRITICAL Security Rules

Token Specifications:

Algorithm: RS256 (RSA public/private key pairs)
Expiration: 30 seconds (short-lived by design)
Auto-refresh: Generate new token when <5s remain before expiry
Payload: { dataJwtId, clientName, exp, iat }

Key File Locations:

Local development: getSecretsSqlClientApiKeysPath() → ~/cwc/private/cwc-secrets/sql-client-api-keys/
Server deployment: ./sql-client-api-keys/

CORS Configuration - Express Middleware (CRITICAL)

CORS is handled exclusively by Express middleware, NOT nginx.

This is a deliberate architectural decision (session 045):

Per-service method control: Each service specifies allowGet, allowPost, allowOptions
Environment-aware logic: Different behavior for dev/test/prod built into middleware
Integrated pattern: Automatically applied via createExpressService()
No duplication: Single source of truth for CORS configuration

CRITICAL: nginx must NOT add CORS headers. Duplicate CORS headers (from both nginx and Express) cause browsers to reject responses entirely.

Environment-Specific Behavior

Dev (isDev: true) / E2E (isE2E: true):

Reflects request origin in Access-Control-Allow-Origin
Allows credentials
Wide open for local development

Test (isTest: true):

Allows devCorsOrigin for localhost development against test services
Falls back to corsOrigin for other requests
Enables running local website (localhost:5173) against test backend services

Prod (isProd: true):

Strict corsOrigin only
No dynamic origins

Configuration Values

Config Property	Purpose	Example
`corsOrigin`	Allowed origin for test/prod	`test.codingwithclaude.dev`
`devCorsOrigin`	Localhost origin for local dev	`http://localhost:5173`

Note: devCorsOrigin uses port 5173 (Vite/React Router), not 3000 (Next.js legacy).

Troubleshooting CORS Issues

If experiencing CORS problems:

Check nginx templates - Ensure CORS headers are NOT set in nginx (Express handles CORS)
Verify the API route exists - Non-existent routes won't return proper OPTIONS response
Check devCorsOrigin port - Must match your local dev server (5173 for Vite)
Check for duplicate headers - Use browser dev tools Network tab to inspect response headers

Rate Limiting Configuration

Configurable via BackendUtilsConfig:

rateLimiterPoints - Max requests per duration (default: 100)
rateLimiterDuration - Time window in seconds (default: 60)
Returns 429 status when exceeded
Memory-based rate limiting per IP

Path Helpers

expandTilde - Tilde Path Expansion

Location: src/configHelpers.ts

CRITICAL: Node.js path.join() does NOT expand ~ - it treats it as a literal character.

// ❌ WRONG - creates literal "~" directory
path.join('~/storage', 'file.txt');  // Returns: "~/storage/file.txt"

// ✅ CORRECT - use expandTilde helper
import { expandTilde } from 'cwc-backend-utils';
expandTilde('~/storage');  // Returns: "/Users/username/storage"

Usage:

import { expandTilde } from 'cwc-backend-utils';

// In loadConfig.ts for paths that may contain ~
storageVolumePath: expandTilde(requireEnv('STORAGE_VOLUME_PATH')),
storageLogPath: expandTilde(optionalEnv('STORAGE_LOG_PATH', './logs')),

When to use:

Any config value that represents a file/directory path
Paths read from .env files that may contain ~
Local development paths (e.g., ~/dev-cwc-storage)

When NOT needed:

Container paths (e.g., /data/storage) - no tilde to expand
Relative paths (e.g., ./logs) - no tilde

Local Secrets Path Functions

Location: src/localSecretsPaths.ts

Centralized path functions for local development secrets using os.homedir().

Path Resolution:

Local (dev/unit/e2e): Uses absolute paths via os.homedir() → ~/cwc/private/cwc-secrets
Server (test/prod): Uses relative paths from deployment directory (e.g., ./sql-client-api-keys)

Functions:

Function	Returns (local)	Returns (server)
`getSecretsPath()`	`~/cwc/private/cwc-secrets`	N/A (local only)
`getSecretsEnvPath()`	`{base}/env`	N/A (local only)
`getSecretsSqlClientApiKeysPath(runningLocally)`	`{base}/sql-client-api-keys`	`./sql-client-api-keys`
`getSecretsConfigHelperPath(runningLocally)`	`{base}/configuration-helper`	`./configuration-helper`
`getSecretsDeploymentPath(runningLocally)`	`{base}/deployment`	`./deployment`
`getSecretsEnvFilePath(runningLocally, env, service)`	`{base}/env/{env}.{service}.env`	`.env.{env}`

Usage:

import { getSecretsEnvFilePath, getSecretsSqlClientApiKeysPath } from 'cwc-backend-utils';

const runningLocally = config.isDev || config.isUnit || config.isE2E;

// Get .env file path (encapsulates local vs server logic)
const envPath = getSecretsEnvFilePath(runningLocally, 'dev', 'cwc-api');
// Local: /Users/.../cwc/private/cwc-secrets/env/dev.cwc-api.env
// Server: .env.dev

// Get SQL keys path (encapsulates local vs server logic)
const keysPath = getSecretsSqlClientApiKeysPath(runningLocally);
// Local: /Users/.../cwc/private/cwc-secrets/sql-client-api-keys
// Server: ./sql-client-api-keys

Environment Loading - loadDotEnv

loadDotEnv Path Resolution:

Local development (dev/unit/e2e):

Uses getSecretsEnvFilePath(environment, serviceName)
Path: ~/cwc/private/cwc-secrets/env/{environment}.{serviceName}.env

Server deployment (test/prod):

Path: .env.{environment} relative to process.cwd()

CRITICAL: Data path pattern MUST include service name to prevent conflicts:

Pattern: {deploymentName}-{serviceName}/data
Example: test-cwc-database/data vs test-mariadb/data

Logger Error Handling

Direct Database Write:

Logger uses SqlClient internally to write to errorLog table
Automatically truncates fields to DB limits (error: 2000 chars, stack: 2000 chars)
Extracts message and stack from Error objects
JSON serializes objects automatically
Tags all logs with serviceName
Debug mode only: logInformation and logDebug output

Express Service Factory - Built-in Middleware

Automatically applies (in order):

Rate Limiter - Memory-based per IP
Helmet - Security headers
CORS - Environment-specific origins
Invalid Routes - Blocks non-registered paths
Error Handling - Captures and logs errors

Invalid Routes Protection:

Rejects HTTP methods not in allowGet/allowPost/allowOptions
Rejects paths that don't start with registered API paths
Returns 400 status with "unsupported" message

Request Utilities

getRemoteIpAddress(req) resolution order:

x-real-ip header (set by nginx proxy)
origin header hostname
req.ip (strips ::ffff: IPv6 prefix if present)

Critical Bugs to Avoid

Environment Variables:

Use process.env['VAR_NAME'] bracket notation (not dot notation)
Use 'dev' not 'development' (matches RuntimeEnvironment type)
Use 'prod' not 'production'

Type Safety:

Extend Express.Request in global namespace, not express-serve-static-core

Configuration Types

BackendUtilsConfig: Complete config with SqlClient/database features

Includes: dataUri, logErrorsToDatabase

BackendUtilsConfigBasic: Simplified config without SqlClient

Omits: dataUri, logErrorsToDatabase
Use for services that don't need database access

Node.js Compatibility

Node.js-only package:

✅ CAN use Node.js APIs (fs, path, crypto, os, http, etc.)
✅ CAN use Node.js-specific packages
❌ NOT browser-compatible
Target: Node.js 22+

Adding New Utilities

Utilities that belong here:

File system operations
Environment configuration helpers
Server-side hashing/crypto
Request/response formatting
Error handling utilities
Logging helpers
JWT utilities
API response builders
Node.js-specific validation

Utilities that DON'T belong here:

Cross-platform utilities → Use cwc-utils
Type definitions → Use cwc-types
Schema definitions → Use cwc-schema
Database queries → Use cwc-database or cwc-sql

Related Packages

Consumed By:

cwc-api, cwc-auth, cwc-admin-api, cwc-sql - All backend microservices
cwc-content - Content delivery service
cwc-session-importer - CLI for importing sessions (uses ApiClient, ContentClient)

Depends On:

cwc-types (workspace) - Shared TypeScript types

packages/cwc-backend-utils/src/express/cors.ts

2 versions

Version 1

'use strict';

/**
 * CORS middleware - DISABLED
 *
 * CORS is now handled by nginx for centralized control.
 * See cwc-deployment nginx templates for CORS configuration.
 *
 * This file is preserved for reference in case we need to revert
 * to Express-based CORS handling in the future.
 */

/*
import { NextFunction, Request, Response } from 'express';
import { ExpressCorsOptions } from '../backendUtils.types';

// Enable CORS for all methods
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin

export const cors = ({ config, allowGet, allowOptions, allowPost }: ExpressCorsOptions) => {
  return (req: Request, res: Response, next: NextFunction) => {
    // *****************************************************************************************
    // having cors problems?
    // 1. nginx server.conf - make sure you have updated the nginx server.conf file and DEPLOYED it to the server
    // 2. have you added the api in ./src/index.ts ?
    //   const apis: AuthApi[] = [new LogonApiV1()];
    // 2. is the uri/url correct? if a route can't be found it will not return OK for OPTIONS
    //   route: /auth/v1/logon
    //   request path: /auth/auth/v1/logon  <-- will fail
    // *****************************************************************************************

    if (config.isDev || config.isE2E) {
      if (req.headers.origin) {
        res.header('Access-Control-Allow-Origin', req.headers.origin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', '*');
      }
    }

    if (config.isTest) {
      // Allow devCorsOrigin for localhost development against test services
      // (Browser security enforces origin headers - they cannot be forged)
      if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
        res.header('Access-Control-Allow-Origin', config.devCorsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', config.corsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      }
    }

    if (config.isProd) {
      res.header('Access-Control-Allow-Origin', config.corsOrigin);
      res.header('Vary', 'Origin');
      res.header('Access-Control-Allow-Credentials', 'true');
    }

    res.header(
      'Access-Control-Allow-Headers',
      'Authorization, Origin, X-Requested-With, Content-Type, Accept'
    );

    const allowedMethods: string[] = [];
    if (allowGet) {
      allowedMethods.push('GET');
    }
    if (allowOptions) {
      allowedMethods.push('OPTIONS');
    }
    if (allowPost) {
      allowedMethods.push('POST');
    }
    res.header('Access-Control-Allow-Methods', allowedMethods.join());
    res.header('Access-Control-Expose-Headers', 'Authorization');
    next();
  };
};
*/

Version 2 (latest)

'use strict';

import { NextFunction, Request, Response } from 'express';
import { ExpressCorsOptions } from '../backendUtils.types';

// Enable CORS for all methods
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin

export const cors = ({ config, allowGet, allowOptions, allowPost }: ExpressCorsOptions) => {
  return (req: Request, res: Response, next: NextFunction) => {
    // *****************************************************************************************
    // having cors problems?
    // 1. nginx server.conf - make sure CORS headers are NOT set in nginx (Express handles CORS)
    // 2. have you added the api in ./src/index.ts ?
    //   const apis: AuthApi[] = [new LogonApiV1()];
    // 2. is the uri/url correct? if a route can't be found it will not return OK for OPTIONS
    //   route: /auth/v1/logon
    //   request path: /auth/auth/v1/logon  <-- will fail
    // *****************************************************************************************

    if (config.isDev || config.isE2E) {
      if (req.headers.origin) {
        res.header('Access-Control-Allow-Origin', req.headers.origin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', '*');
      }
    }

    if (config.isTest) {
      // Allow devCorsOrigin for localhost development against test services
      // (Browser security enforces origin headers - they cannot be forged)
      if (config.devCorsOrigin && req.headers.origin === config.devCorsOrigin) {
        res.header('Access-Control-Allow-Origin', config.devCorsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      } else {
        res.header('Access-Control-Allow-Origin', config.corsOrigin);
        res.header('Vary', 'Origin');
        res.header('Access-Control-Allow-Credentials', 'true');
      }
    }

    if (config.isProd) {
      res.header('Access-Control-Allow-Origin', config.corsOrigin);
      res.header('Vary', 'Origin');
      res.header('Access-Control-Allow-Credentials', 'true');
    }

    res.header(
      'Access-Control-Allow-Headers',
      'Authorization, Origin, X-Requested-With, Content-Type, Accept'
    );

    const allowedMethods: string[] = [];
    if (allowGet) {
      allowedMethods.push('GET');
    }
    if (allowOptions) {
      allowedMethods.push('OPTIONS');
    }
    if (allowPost) {
      allowedMethods.push('POST');
    }
    res.header('Access-Control-Allow-Methods', allowedMethods.join());
    res.header('Access-Control-Expose-Headers', 'Authorization');
    next();
  };
};

packages/cwc-backend-utils/src/express/service.ts

3 versions

Version 1

'use strict';
import express from 'express';
import helmet from 'helmet';
import { rateLimiter } from './rateLimiter';
import http from 'node:http';
import { invalidRoutes } from './invalidRoutes';
// CORS now handled by nginx - see cwc-deployment nginx templates
// import { cors } from './cors';
import { Logger } from '../Logger';
import {
  BackendUtilsConfig,
  ExpressApi,
  ExpressService,
  ExpressServiceOptions,
} from '../backendUtils.types';

const codeLocation = 'express/service.ts';

export const createExpressService = ({
  config: configProp,
  serviceName,
  allowGet,
  allowOptions,
  allowPost,
  payloadLimit,
}: ExpressServiceOptions): ExpressService => {
  const expressApp = express();

  // intentionally cast configProp to BackendUtilsConfig
  const config = configProp as BackendUtilsConfig;

  if (payloadLimit) {
    // allow larger payloads in cases where we want to supports larger payloads such as image uploads
    expressApp.use(express.json({ limit: payloadLimit }));
    expressApp.use(express.urlencoded({ limit: payloadLimit, extended: true }));
  }

  const httpServer = http.createServer(expressApp);

  const service: ExpressService = {
    expressApp,
    httpServer,
    start(apis: ExpressApi[]) {
      // if the 'config' object provided was BackendUtilsConfigBasic: dataUriInternal, and logErrorsToDatabase
      // will be undefined - in that case we do not want to enable the Logger
      const enableLogger = Boolean(config.dataUriInternal && config.logErrorsToDatabase !== undefined);

      const logger = enableLogger ? new Logger({ config, serviceName }) : undefined;

      expressApp.use(rateLimiter({ config }));
      expressApp.use(helmet());
      expressApp.disable('x-powered-by');
      expressApp.use(cors({ config, allowGet, allowOptions, allowPost }));
      expressApp.use(express.json());
      expressApp.use(invalidRoutes({ apis, allowGet, allowOptions, allowPost }));

      // configure each api/version
      apis.forEach((api) => {
        const router = express.Router();

        // error handling on all methods request and response
        router.use(function (req, res, next) {
          req.on('error', (error) => {
            logger?.logError({
              userPkId: undefined,
              codeLocation,
              message: 'router - request - ERROR',
              error,
            });
            res.statusCode = 500;
            res.json({ message: req.path + ' Failed.' });
          });
          res.on('error', (error) => {
            logger?.logError({
              userPkId: undefined,
              codeLocation,
              message: 'router - response - ERROR',
              error,
            });
            res.statusCode = 500;
            res.json({ message: req.path + ' Failed.' });
          });
          next();
        });

        // important: need .bind(api) to prevent 'this' from being undefined in the class
        // Express 5 / path-to-regexp 8.x syntax: use {*splat} for wildcard routes
        if (allowGet) {
          router.get('/{*splat}', api.handler.bind(api));
        }
        if (allowPost) {
          router.post('/{*splat}', api.handler.bind(api));
        }

        expressApp.use(api.path, router);
        if (config.debugMode) {
          logger?.logInformation({
            userPkId: undefined,
            codeLocation,
            message: 'express.service.api.path',
            value: { path: api.path },
          });
        }
      });

      httpServer.listen(config.servicePort, () => {
        if (config.debugMode) {
          logger?.logInformation({
            userPkId: undefined,
            codeLocation,
            message: `listening on port ${config.servicePort}`,
          });
        }
      });
    },
  };

  return service;
};

Version 2

'use strict';
import express from 'express';
import helmet from 'helmet';
import { rateLimiter } from './rateLimiter';
import http from 'node:http';
import { invalidRoutes } from './invalidRoutes';
// CORS now handled by nginx - see cwc-deployment nginx templates
// import { cors } from './cors';
import { Logger } from '../Logger';
import {
  BackendUtilsConfig,
  ExpressApi,
  ExpressService,
  ExpressServiceOptions,
} from '../backendUtils.types';

const codeLocation = 'express/service.ts';

export const createExpressService = ({
  config: configProp,
  serviceName,
  allowGet,
  allowOptions,
  allowPost,
  payloadLimit,
}: ExpressServiceOptions): ExpressService => {
  const expressApp = express();

  // intentionally cast configProp to BackendUtilsConfig
  const config = configProp as BackendUtilsConfig;

  if (payloadLimit) {
    // allow larger payloads in cases where we want to supports larger payloads such as image uploads
    expressApp.use(express.json({ limit: payloadLimit }));
    expressApp.use(express.urlencoded({ limit: payloadLimit, extended: true }));
  }

  const httpServer = http.createServer(expressApp);

  const service: ExpressService = {
    expressApp,
    httpServer,
    start(apis: ExpressApi[]) {
      // if the 'config' object provided was BackendUtilsConfigBasic: dataUriInternal, and logErrorsToDatabase
      // will be undefined - in that case we do not want to enable the Logger
      const enableLogger = Boolean(config.dataUriInternal && config.logErrorsToDatabase !== undefined);

      const logger = enableLogger ? new Logger({ config, serviceName }) : undefined;

      expressApp.use(rateLimiter({ config }));
      expressApp.use(helmet());
      expressApp.disable('x-powered-by');
      // CORS now handled by nginx - see cwc-deployment nginx templates
      // expressApp.use(cors({ config, allowGet, allowOptions, allowPost }));
      expressApp.use(express.json());
      expressApp.use(invalidRoutes({ apis, allowGet, allowOptions, allowPost }));

      // configure each api/version
      apis.forEach((api) => {
        const router = express.Router();

        // error handling on all methods request and response
        router.use(function (req, res, next) {
          req.on('error', (error) => {
            logger?.logError({
              userPkId: undefined,
              codeLocation,
              message: 'router - request - ERROR',
              error,
            });
            res.statusCode = 500;
            res.json({ message: req.path + ' Failed.' });
          });
          res.on('error', (error) => {
            logger?.logError({
              userPkId: undefined,
              codeLocation,
              message: 'router - response - ERROR',
              error,
            });
            res.statusCode = 500;
            res.json({ message: req.path + ' Failed.' });
          });
          next();
        });

        // important: need .bind(api) to prevent 'this' from being undefined in the class
        // Express 5 / path-to-regexp 8.x syntax: use {*splat} for wildcard routes
        if (allowGet) {
          router.get('/{*splat}', api.handler.bind(api));
        }
        if (allowPost) {
          router.post('/{*splat}', api.handler.bind(api));
        }

        expressApp.use(api.path, router);
        if (config.debugMode) {
          logger?.logInformation({
            userPkId: undefined,
            codeLocation,
            message: 'express.service.api.path',
            value: { path: api.path },
          });
        }
      });

      httpServer.listen(config.servicePort, () => {
        if (config.debugMode) {
          logger?.logInformation({
            userPkId: undefined,
            codeLocation,
            message: `listening on port ${config.servicePort}`,
          });
        }
      });
    },
  };

  return service;
};

Version 3 (latest)

'use strict';
import express from 'express';
import helmet from 'helmet';
import { rateLimiter } from './rateLimiter';
import http from 'node:http';
import { invalidRoutes } from './invalidRoutes';
import { cors } from './cors';
import { Logger } from '../Logger';
import {
  BackendUtilsConfig,
  ExpressApi,
  ExpressService,
  ExpressServiceOptions,
} from '../backendUtils.types';

const codeLocation = 'express/service.ts';

export const createExpressService = ({
  config: configProp,
  serviceName,
  allowGet,
  allowOptions,
  allowPost,
  payloadLimit,
}: ExpressServiceOptions): ExpressService => {
  const expressApp = express();

  // intentionally cast configProp to BackendUtilsConfig
  const config = configProp as BackendUtilsConfig;

  if (payloadLimit) {
    // allow larger payloads in cases where we want to supports larger payloads such as image uploads
    expressApp.use(express.json({ limit: payloadLimit }));
    expressApp.use(express.urlencoded({ limit: payloadLimit, extended: true }));
  }

  const httpServer = http.createServer(expressApp);

  const service: ExpressService = {
    expressApp,
    httpServer,
    start(apis: ExpressApi[]) {
      // if the 'config' object provided was BackendUtilsConfigBasic: dataUriInternal, and logErrorsToDatabase
      // will be undefined - in that case we do not want to enable the Logger
      const enableLogger = Boolean(config.dataUriInternal && config.logErrorsToDatabase !== undefined);

      const logger = enableLogger ? new Logger({ config, serviceName }) : undefined;

      expressApp.use(rateLimiter({ config }));
      expressApp.use(helmet());
      expressApp.disable('x-powered-by');
      expressApp.use(cors({ config, allowGet, allowOptions, allowPost }));
      expressApp.use(express.json());
      expressApp.use(invalidRoutes({ apis, allowGet, allowOptions, allowPost }));

      // configure each api/version
      apis.forEach((api) => {
        const router = express.Router();

        // error handling on all methods request and response
        router.use(function (req, res, next) {
          req.on('error', (error) => {
            logger?.logError({
              userPkId: undefined,
              codeLocation,
              message: 'router - request - ERROR',
              error,
            });
            res.statusCode = 500;
            res.json({ message: req.path + ' Failed.' });
          });
          res.on('error', (error) => {
            logger?.logError({
              userPkId: undefined,
              codeLocation,
              message: 'router - response - ERROR',
              error,
            });
            res.statusCode = 500;
            res.json({ message: req.path + ' Failed.' });
          });
          next();
        });

        // important: need .bind(api) to prevent 'this' from being undefined in the class
        // Express 5 / path-to-regexp 8.x syntax: use {*splat} for wildcard routes
        if (allowGet) {
          router.get('/{*splat}', api.handler.bind(api));
        }
        if (allowPost) {
          router.post('/{*splat}', api.handler.bind(api));
        }

        expressApp.use(api.path, router);
        if (config.debugMode) {
          logger?.logInformation({
            userPkId: undefined,
            codeLocation,
            message: 'express.service.api.path',
            value: { path: api.path },
          });
        }
      });

      httpServer.listen(config.servicePort, () => {
        if (config.debugMode) {
          logger?.logInformation({
            userPkId: undefined,
            codeLocation,
            message: `listening on port ${config.servicePort}`,
          });
        }
      });
    },
  };

  return service;
};

packages/cwc-configuration-helper/src/configuration.ts

import type { RuntimeEnvironment } from 'cwc-types';

// Re-export for cwc-deployment to avoid direct cwc-types dependency
export type { RuntimeEnvironment };

/*
----------------------------------------------------------
Service Configuration
----------------------------------------------------------

Service ports (used for both Docker and localhost development):

service               port
-------               ----
cwc-admin-api         5004
cwc-auth              5005
cwc-content           5008
cwc-sql               5020
cwc-storage           5030
cwc-api               5040
cwc-website           (nginx)
cwc-dashboard         (nginx)

For Docker Compose deployments, services communicate via DNS names (e.g., cwc-sql:5020).
For localhost development, services communicate via localhost (e.g., localhost:5020).

See docker-compose-upgrade.md in cwc-deployment for migration details.
*/

export type RuntimeConfigValues = {
  corsOrigin: string;
  devCorsOrigin: string;
  // Internal URIs (Docker DNS names for backend-to-backend communication)
  authUriInternal: string;
  apiUriInternal: string;
  dataUriInternal: string;
  storageUriInternal: string;
  contentUriInternal: string;
  // External URIs (public URLs for frontend apps / browser access)
  authUriExternal: string;
  apiUriExternal: string;
  contentUriExternal: string;
  appUrl: string;
  debugMode: boolean; // maps to ON | OFF
  logErrorsToDatabase: boolean; // maps to ON | OFF
  userJwtExpiresIn: string;
  userJwtExpiresInKulo: string;
  tempJwtExpiresIn: string;
  smtp:
    | {
        useSandbox: boolean; // maps to ON | OFF
        sandboxAddress: string; // recipient email when sandbox is ON
        serviceName: string;
        authType: string; // OAuth2
        senderAddress: string;
        senderName: string;
      }
    | undefined;
  endToEndMockValues: Record<string, string> | undefined;
  databaseServer: string;
  databasePort: number;
  databaseName: string;
  databaseConnectTimeout: number;
  databaseConnectionAcquireTimeout: number;
  databaseConnectionQueueLimit: number;
  databaseConnectionLimit: number;
  queryCacheEnabled: boolean;
  queryCacheTtl: number; // minutes
  queryCacheMaxKeys: number;
  storageVolumePath: string; // cwc-storage service
  storageLogPath: string; // cwc-storage service
  contentCacheMaxSize: number; // cwc-content cache max entries
  contentCacheTtlMs: number; // cwc-content cache TTL in milliseconds
  contentPayloadLimit: string; // cwc-content max upload size (e.g., '10mb')
  storagePayloadLimit: string; // cwc-storage max upload size (e.g., '10mb')
  sqlConnectionDebugMode: boolean; // cwc-sql verbose mariadb packet logging
  // cwc-session-importer paths (Claude Code data locations)
  sessionImporterProjectsPath: string;
  sessionImporterFileHistoryPath: string;
  // cwc-session-importer auto-login credentials (optional - can use --jwt instead)
  sessionImporterUsername: string | undefined;
  // Rate limiting (environment-specific: dev is generous, prod is strict)
  rateLimiterPoints: number; // Max requests per duration
  rateLimiterDuration: number; // Time window in seconds
  // cwc-website content display mode
  websiteContentMode: 'Full' | 'Minimal';
};

type RuntimeConfigs = Record<RuntimeEnvironment, RuntimeConfigValues>;

const runtimeConfigs: RuntimeConfigs = {
  prod: {
    corsOrigin: 'codingwithclaude.dev',
    devCorsOrigin: 'http://localhost:5173',
    authUriInternal: 'http://cwc-auth:5005/auth/v1',
    apiUriInternal: 'http://cwc-api:5040/api/v1',
    dataUriInternal: 'http://cwc-sql:5020/data/v1',
    storageUriInternal: 'http://cwc-storage:5030/storage/v1',
    contentUriInternal: 'http://cwc-content:5008/content/v1',
    authUriExternal: 'https://auth.codingwithclaude.dev/auth/v1',
    apiUriExternal: 'https://api.codingwithclaude.dev/api/v1',
    contentUriExternal: 'https://content.codingwithclaude.dev/content/v1',
    logErrorsToDatabase: true,
    userJwtExpiresIn: '15m',
    userJwtExpiresInKulo: '30d',
    tempJwtExpiresIn: '5m',
    appUrl: 'https://codingwithclaude.dev',
    debugMode: false,
    smtp: {
      useSandbox: false,
      sandboxAddress: 'sandbox@codingwithclaude.dev',
      serviceName: 'gmail',
      authType: 'OAuth2',
      senderAddress: 'support@codingwithclaude.dev',
      senderName: 'Coding with Claude',
    },
    endToEndMockValues: undefined,
    databaseServer: 'prod-cwc-database',
    databasePort: 3381,
    databaseName: 'cwc',
    databaseConnectTimeout: 10000,
    databaseConnectionAcquireTimeout: 30000,
    databaseConnectionQueueLimit: 1000,
    databaseConnectionLimit: 20,
    queryCacheEnabled: true,
    queryCacheTtl: 5, // minutes
    queryCacheMaxKeys: 1000,
    storageVolumePath: '/data/storage', // container mount point (host: /home/devops/prod-cwc-storage)
    storageLogPath: '/data/logs', // container mount point (host: /home/devops/prod-cwc-storage-logs)
    contentCacheMaxSize: 100,
    contentCacheTtlMs: 300000, // 5 minutes
    contentPayloadLimit: '10mb',
    storagePayloadLimit: '10mb',
    sqlConnectionDebugMode: false,
    sessionImporterProjectsPath: '~/cwc/claude-code-transcripts/sessions', // session-importer: consolidated transcripts
    sessionImporterFileHistoryPath: '~/cwc/claude-code-transcripts/file-history', // session-importer: consolidated file history
    sessionImporterUsername: 'jeff', // Set in .env for auto-login
    rateLimiterPoints: 15, // Strict rate limiting for production
    rateLimiterDuration: 1,
    websiteContentMode: 'Minimal', // Minimal landing page for prod until full site ready
  },
  test: {
    corsOrigin: 'test.codingwithclaude.dev',
    devCorsOrigin: 'http://localhost:5173',
    authUriInternal: 'http://cwc-auth:5005/auth/v1',
    apiUriInternal: 'http://cwc-api:5040/api/v1',
    dataUriInternal: 'http://cwc-sql:5020/data/v1',
    storageUriInternal: 'http://cwc-storage:5030/storage/v1',
    contentUriInternal: 'http://cwc-content:5008/content/v1',
    // External URIs use private network IP with path-based routing through nginx
    authUriExternal: 'http://172.16.0.6/auth/v1',
    apiUriExternal: 'http://172.16.0.6/api/v1',
    contentUriExternal: 'http://172.16.0.6/content/v1',
    logErrorsToDatabase: true,
    userJwtExpiresIn: '15m',
    userJwtExpiresInKulo: '30d',
    tempJwtExpiresIn: '5m',
    appUrl: 'https://test.codingwithclaude.dev',
    debugMode: true,
    smtp: {
      useSandbox: true,
      sandboxAddress: 'sandbox@codingwithclaude.dev',
      serviceName: 'gmail',
      authType: 'OAuth2',
      senderAddress: 'support@codingwithclaude.dev',
      senderName: 'Coding with Claude',
    },
    endToEndMockValues: undefined,
    databaseServer: 'test-cwc-database',
    databasePort: 3314,
    databaseName: 'cwc',
    databaseConnectTimeout: 10000,
    databaseConnectionAcquireTimeout: 30000,
    databaseConnectionQueueLimit: 1000,
    databaseConnectionLimit: 20,
    queryCacheEnabled: true,
    queryCacheTtl: 5, // minutes
    queryCacheMaxKeys: 1000,
    storageVolumePath: '/data/storage', // container mount point (host: /home/devops/test-cwc-storage)
    storageLogPath: '/data/logs', // container mount point (host: /home/devops/test-cwc-storage-logs)
    contentCacheMaxSize: 100,
    contentCacheTtlMs: 300000, // 5 minutes
    contentPayloadLimit: '10mb',
    storagePayloadLimit: '10mb',
    sqlConnectionDebugMode: false,
    sessionImporterProjectsPath: '~/cwc/claude-code-transcripts/sessions', // session-importer: consolidated transcripts
    sessionImporterFileHistoryPath: '~/cwc/claude-code-transcripts/file-history', // session-importer: consolidated file history
    sessionImporterUsername: 'jeff', // Set in .env for auto-login
    rateLimiterPoints: 100, // Moderate rate limiting for test environment
    rateLimiterDuration: 1,
    websiteContentMode: 'Full', // Minimal landing page for test to review before prod
  },
  dev: {
    corsOrigin: '*',
    devCorsOrigin: 'http://localhost:5173',
    authUriInternal: 'http://localhost:5005/auth/v1',
    apiUriInternal: 'http://localhost:5040/api/v1',
    dataUriInternal: 'http://localhost:5020/data/v1',
    storageUriInternal: 'http://localhost:5030/storage/v1',
    contentUriInternal: 'http://localhost:5008/content/v1',
    authUriExternal: 'http://localhost:5005/auth/v1',
    apiUriExternal: 'http://localhost:5040/api/v1',
    contentUriExternal: 'http://localhost:5008/content/v1',
    logErrorsToDatabase: true,
    userJwtExpiresIn: '15m',
    userJwtExpiresInKulo: '30d',
    tempJwtExpiresIn: '5m',
    appUrl: 'http://localhost:3000',
    debugMode: true,
    smtp: {
      useSandbox: true,
      sandboxAddress: 'sandbox@codingwithclaude.dev',
      serviceName: 'gmail',
      authType: 'OAuth2',
      senderAddress: 'support@codingwithclaude.dev',
      senderName: 'Coding with Claude',
    },
    endToEndMockValues: undefined,
    databaseServer: '172.16.0.6', // dev points to test server over private/local network. firewall on test server must allow port 3314
    databasePort: 3314,
    databaseName: 'cwc',
    databaseConnectTimeout: 10000,
    databaseConnectionAcquireTimeout: 30000,
    databaseConnectionQueueLimit: 1000,
    databaseConnectionLimit: 20,
    queryCacheEnabled: true,
    queryCacheTtl: 5, // minutes
    queryCacheMaxKeys: 1000,
    storageVolumePath: '~/dev-cwc-storage',
    storageLogPath: '~/dev-cwc-storage-logs',
    contentCacheMaxSize: 100,
    contentCacheTtlMs: 300000, // 5 minutes
    contentPayloadLimit: '10mb',
    storagePayloadLimit: '10mb',
    sqlConnectionDebugMode: false,
    sessionImporterProjectsPath: '~/cwc/claude-code-transcripts/sessions', // session-importer: consolidated transcripts
    sessionImporterFileHistoryPath: '~/cwc/claude-code-transcripts/file-history', // session-importer: consolidated file history
    sessionImporterUsername: 'jeff', // Set in .env for auto-login
    rateLimiterPoints: 1000, // Generous rate limiting for local development
    rateLimiterDuration: 1,
    websiteContentMode: 'Full', // Full content for local development
  },
  unit: {
    corsOrigin: '*',
    devCorsOrigin: 'http://localhost:5173',
    authUriInternal: 'http://localhost:5005/auth/v1',
    apiUriInternal: 'http://localhost:5040/api/v1',
    dataUriInternal: 'http://localhost:5020/data/v1',
    storageUriInternal: 'http://localhost:5030/storage/v1',
    contentUriInternal: 'http://localhost:5008/content/v1',
    authUriExternal: 'http://localhost:5005/auth/v1',
    apiUriExternal: 'http://localhost:5040/api/v1',
    contentUriExternal: 'http://localhost:5008/content/v1',
    logErrorsToDatabase: false,
    userJwtExpiresIn: '15m',
    userJwtExpiresInKulo: '30d',
    tempJwtExpiresIn: '5m',
    appUrl: 'http://localhost:3000',
    debugMode: false,
    smtp: {
      useSandbox: true,
      sandboxAddress: 'sandbox@codingwithclaude.dev',
      serviceName: 'gmail',
      authType: 'OAuth2',
      senderAddress: 'support@codingwithclaude.dev',
      senderName: 'Coding with Claude',
    },
    endToEndMockValues: undefined,
    databaseServer: 'unit-cwc-database',
    databasePort: 3306,
    databaseName: 'cwc',
    databaseConnectTimeout: 10000,
    databaseConnectionAcquireTimeout: 30000,
    databaseConnectionQueueLimit: 1000,
    databaseConnectionLimit: 20,
    queryCacheEnabled: true,
    queryCacheTtl: 5, // minutes
    queryCacheMaxKeys: 1000,
    storageVolumePath: '~/unit-cwc-storage',
    storageLogPath: '~/unit-cwc-storage-logs',
    contentCacheMaxSize: 100,
    contentCacheTtlMs: 300000, // 5 minutes
    contentPayloadLimit: '10mb',
    storagePayloadLimit: '10mb',
    sqlConnectionDebugMode: false,
    sessionImporterProjectsPath: '~/cwc/claude-code-transcripts/sessions', // session-importer: consolidated transcripts
    sessionImporterFileHistoryPath: '~/cwc/claude-code-transcripts/file-history', // session-importer: consolidated file history
    sessionImporterUsername: 'jeff', // Set in .env for auto-login
    rateLimiterPoints: 1000, // Generous rate limiting for unit tests
    rateLimiterDuration: 1,
    websiteContentMode: 'Full', // Full content for unit tests
  },
  e2e: {
    corsOrigin: '*',
    devCorsOrigin: 'http://localhost:5173',
    authUriInternal: 'http://localhost:5005/auth/v1',
    apiUriInternal: 'http://localhost:5040/api/v1',
    dataUriInternal: 'http://localhost:5020/data/v1',
    storageUriInternal: 'http://localhost:5030/storage/v1',
    contentUriInternal: 'http://localhost:5008/content/v1',
    authUriExternal: 'http://localhost:5005/auth/v1',
    apiUriExternal: 'http://localhost:5040/api/v1',
    contentUriExternal: 'http://localhost:5008/content/v1',
    logErrorsToDatabase: false,
    userJwtExpiresIn: '15m',
    userJwtExpiresInKulo: '30d',
    tempJwtExpiresIn: '5m',
    appUrl: 'http://localhost:3000',
    debugMode: false,
    smtp: {
      useSandbox: true,
      sandboxAddress: 'sandbox@codingwithclaude.dev',
      serviceName: 'gmail',
      authType: 'OAuth2',
      senderAddress: 'support@codingwithclaude.dev',
      senderName: 'Coding with Claude',
    },
    endToEndMockValues: {
      testValue: 'just a test',
    },
    databaseServer: '172.16.0.6', // e2e points to test server over private/local network. firewall on test server must allow port 3314
    databasePort: 3318, // we need to deploy an e2e database container to support this
    databaseName: 'cwc',
    databaseConnectTimeout: 10000,
    databaseConnectionAcquireTimeout: 30000,
    databaseConnectionQueueLimit: 1000,
    databaseConnectionLimit: 20,
    queryCacheEnabled: true,
    queryCacheTtl: 5, // minutes
    queryCacheMaxKeys: 1000,
    storageVolumePath: '~/e2e-cwc-storage', // folder must be created on the test server
    storageLogPath: '~/e2e-cwc-storage-logs', // folder must be created on the test server
    contentCacheMaxSize: 100,
    contentCacheTtlMs: 300000, // 5 minutes
    contentPayloadLimit: '10mb',
    storagePayloadLimit: '10mb',
    sqlConnectionDebugMode: false,
    sessionImporterProjectsPath: '~/cwc/claude-code-transcripts/sessions', // session-importer: consolidated transcripts
    sessionImporterFileHistoryPath: '~/cwc/claude-code-transcripts/file-history', // session-importer: consolidated file history
    sessionImporterUsername: 'jeff', // Set in .env for auto-login
    rateLimiterPoints: 1000, // Generous rate limiting for e2e tests
    rateLimiterDuration: 1,
    websiteContentMode: 'Full', // Full content for e2e tests
  },
};

// Services can optionally override runtime config values
export type ServiceConfigValues = Partial<RuntimeConfigValues> & {
  // The port that the service listens on
  port: number | undefined;
};

export type ServiceName =
  | 'cwc-api'
  | 'cwc-auth'
  | 'cwc-sql'
  | 'cwc-storage'
  | 'cwc-website'
  | 'cwc-dashboard'
  | 'cwc-content'
  | 'cwc-admin-api'
  | 'cwc-session-importer';

type ServiceConfigs = Record<ServiceName, ServiceConfigValues>;

const serviceConfigs: ServiceConfigs = {
  'cwc-api': { port: 5040 },
  'cwc-auth': { port: 5005 },
  'cwc-sql': { port: 5020 },
  'cwc-storage': { port: 5030 },
  'cwc-website': { port: undefined },
  'cwc-dashboard': { port: undefined },
  'cwc-content': { port: 5008 },
  'cwc-admin-api': { port: 5004 },
  'cwc-session-importer': { port: undefined },
};

/**
 * Gets the merged configuration for a service in a specific runtime environment.
 * Service-specific values override runtime defaults.
 */
export const getConfig = (
  runtimeEnv: RuntimeEnvironment,
  serviceName: ServiceName
): ServiceConfigValues => {
  const runtimeValues = runtimeConfigs[runtimeEnv];
  const serviceValues = serviceConfigs[serviceName];

  // Allow serviceValues to override runtimeValues
  return {
    ...runtimeValues,
    ...serviceValues,
  };
};

/**
 * Checks if a package name is a known service
 */
export const isKnownService = (packageName: string): packageName is ServiceName => {
  return packageName in serviceConfigs;
};

/**
 * Gets the runtime configuration for a specific environment.
 * Used by cwc-deployment to access environment-specific values like databasePort.
 */
export const getRuntimeConfig = (env: RuntimeEnvironment): RuntimeConfigValues => {
  return runtimeConfigs[env];
};

packages/cwc-deployment/CLAUDE.md

cwc-deployment Package

Isolated deployment CLI for CWC services with truly isolated deployments per target.

Critical Design Principles

NO LEGACY SUPPORT: This app is in initial development, not production. Do NOT create backward-compatibility or legacy support functionality.

Architecture Overview

6 Isolated Deployment Targets:

Target	Container Type	Script	Notes
Database	Standalone container	`deploy-database.sh`
Services	docker-compose	`deploy-services.sh`
nginx	docker-compose	`deploy-nginx.sh`	Base domain auto-derived from env
Website (SSR)	docker-compose	`deploy-website.sh`	Test only - prod uses SSG
Website Build (SSG)	Temporary container	`deploy-website-build.sh`	Both test and prod
Dashboard	docker-compose	`deploy-dashboard.sh`

Shared Network: All containers join {env}-cwc-network (external Docker network).

Naming Convention

Pattern: {env}-cwc-{resource}

Data volumes (persistent data, in /home/devops/):

Resource	Example
Network	`test-cwc-network`
Database container	`test-cwc-database`
Database data path	`/home/devops/test-cwc-database`
Storage data path	`/home/devops/test-cwc-storage`
Storage logs path	`/home/devops/test-cwc-storage-logs`
SSL certs path	`/home/devops/test-cwc-certs`
Website build output	`/home/devops/test-cwc-website-build`

Deployment code (docker-compose, configs, in /home/devops/deployment/):

Resource	Example
Services deployment	`/home/devops/deployment/services/test/current/`
nginx deployment	`/home/devops/deployment/nginx/test/current/`
Website (SSR) deployment	`/home/devops/deployment/website/test/current/`
Website-build workspace	`/home/devops/deployment/website-build/test/`

Directory Structure

src/
├── index.ts              # CLI entry point (commander)
├── core/                 # Shared utilities
│   ├── config.ts         # Configuration loading
│   ├── constants.ts      # Centralized constants
│   ├── docker.ts         # Docker command builders
│   ├── logger.ts         # CLI logging with spinners
│   ├── network.ts        # Docker network utilities
│   └── ssh.ts            # SSH connection wrapper
├── commands/             # CLI command handlers
├── database/             # Database deployment logic
├── services/             # Backend services deployment
├── nginx/                # nginx deployment
├── website/              # Website deployment
├── website-build/        # Website SSG build (generates static files)
├── dashboard/            # Dashboard deployment (future)
└── types/                # TypeScript types
    ├── config.ts         # Configuration types
    └── deployment.ts     # Deployment result types

templates/
├── database/
├── services/
├── nginx/
│   ├── nginx.conf.template
│   └── conf.d/
│       ├── default.conf.test.template   # Test: SSR website + static validation site
│       ├── default.conf.prod.template   # Prod: API subdomains only (main site on Cloudflare)
│       └── api-locations.inc.template
└── website/

Database: Standalone Container

Database runs as a standalone Docker container, NOT managed by docker-compose:

docker run -d \
  --name ${env}-cwc-database \
  --network ${env}-cwc-network \
  --restart unless-stopped \
  -e MYSQL_ROOT_PASSWORD=... \
  -e MARIADB_DATABASE=cwc \
  -v /home/devops/${env}-cwc-database:/var/lib/mysql \
  -p ${databasePort}:3306 \
  mariadb:11.8

Port is environment-specific (from cwc-configuration-helper/configuration.ts):

dev: 3381
test: 3314
prod: 3306

Why standalone?

True isolation from service deployments
Database lifecycle independent of application deploys
No accidental restarts when deploying services

Service Connection to Database

Services connect via container name on the shared network:

DATABASE_HOST=${env}-cwc-database   # e.g., test-cwc-database
DATABASE_PORT=3306

Scripts

# Deploy database (first time with schema)
./deployment-scripts/deploy-database.sh test --create-schema

# Deploy services
./deployment-scripts/deploy-services.sh test

# Deploy nginx (base domain auto-derived from env)
./deployment-scripts/deploy-nginx.sh test

# Deploy website (SSR - test only, prod uses SSG)
./deployment-scripts/deploy-website.sh test

# Run website build (SSG - generates static files)
./deployment-scripts/deploy-website-build.sh test
./deployment-scripts/deploy-website-build.sh prod --publish  # Production: build + publish to CDN

Website Deployment - Runtime Env File

CRITICAL: Website (React Router SSR) needs environment variables at RUNTIME, not just build time.

Build Time vs Runtime:

Build time: .env.production copied to package dir → pnpm build → file deleted
Runtime: cwc-website.env included in deployment → loaded via docker-compose env_file

Deployment includes:

deploy/
├── cwc-website/
│   ├── build/           # React Router SSR build output
│   ├── Dockerfile
│   └── package.json
├── cwc-website.env      # Runtime environment variables
└── docker-compose.yml   # References env_file: ./cwc-website.env

docker-compose.yml:

services:
  cwc-website:
    env_file:
      - ./cwc-website.env
    environment:
      - RUNTIME_ENVIRONMENT=test
      - NODE_ENV=production

Common mistake: Forgetting env_file directive causes "Missing required environment variable" errors at runtime.

Website Build (SSG)

Static Site Generation using cwc-website-build Docker container.

The deploy-website-build command runs a temporary container that:

Connects to cwc-api via the Docker network
Discovers all routes (projects, sessions)
Pre-renders all pages to static HTML
Outputs files to /home/devops/{env}-cwc-website-build
Creates .tar.gz archive backup
Optionally publishes to Cloudflare Pages (prod only)
Exits (container is removed)

Usage:

# Build only (test or prod)
./deployment-scripts/deploy-website-build.sh test

# Build and publish to Cloudflare Pages (prod only)
./deployment-scripts/deploy-website-build.sh prod --publish

# List available builds
./deployment-scripts/deploy-website-build.sh prod --list-builds

# Rollback to previous build (updates symlink)
./deployment-scripts/deploy-website-build.sh prod --rollback 2024-12-31-165432

# Rollback and publish that build to CDN
./deployment-scripts/deploy-website-build.sh prod --rollback 2024-12-31-165432 --publish

Directory structure:

/home/devops/{env}-cwc-website-build/
├── current -> builds/2024-12-31-165432   (symlink - nginx serves this)
├── builds/
│   ├── 2024-12-31-165432/                (latest)
│   ├── 2024-12-30-120000/                (previous)
│   └── ...                               (keeps last 5 builds)
├── archives/
│   ├── 2024-12-31-165432.tar.gz          (compressed backups)
│   └── ...                               (keeps last 5 archives)

Static site access: https://static.{server-name} (e.g., static.test.codingwithclaude.dev)

Publishing to Cloudflare Pages (--publish):

Only valid for prod environment

Requires Cloudflare credentials in {secrets-path}/cloudflare/credentials.json:

{
  "apiToken": "your-cloudflare-api-token",
  "accountId": "your-cloudflare-account-id"
}

Publishes to project: coding-with-claude
Uses Wrangler CLI built into the Docker container

Container environment:

API_URI_BUILD=http://cwc-api:5040/api/v1
API_URI_INTERNAL=http://cwc-api:5040/api/v1
PUBLISH=true (when --publish flag is used)
CLOUDFLARE_* credentials (when --publish flag is used)

Note: For test environment, deploy-website-build automatically restarts nginx after the build to pick up new static files. For the first build, you must deploy nginx first to create the volume mount.

Cloudflare Pages project: Must exist before first --publish. Create via Cloudflare dashboard or npx wrangler pages project create coding-with-claude.

Core Utilities

constants.ts

Centralized naming functions and configuration:

NAMING.getNetworkName(env) → {env}-cwc-network
NAMING.getDatabaseContainerName(env) → {env}-cwc-database
NAMING.getDatabaseDataPath(env) → /home/devops/{env}-cwc-database
NAMING.getWebsiteBuildOutputPath(env) → /home/devops/{env}-cwc-website-build
PORTS - Default ports for all services
IMAGES - Docker image versions

network.ts

Docker network management:

ensureExternalNetwork(ssh, env) - Create network if needed
removeNetwork(ssh, env) - Remove network if empty
listNetworkContainers(ssh, env) - List connected containers

docker.ts

Docker container operations:

stopContainer(ssh, containerName) - Stop and remove
containerExists(ssh, containerName) - Check existence
containerRunning(ssh, containerName) - Check if running
waitForHealthy(ssh, containerName, timeout) - Wait for health check
getContainerLogs(ssh, containerName, lines) - Get logs

nginx Environment Templates

Test and prod have different nginx configurations:

Environment	Template	Main Site	Subdomains
test	`default.conf.test.template`	SSR (cwc-website)	api., auth., content., static., dashboard.*
prod	`default.conf.prod.template`	Cloudflare Pages	api., auth., content., dashboard.

Test nginx routes:

test.codingwithclaude.dev → cwc-website:3000 (SSR)
static.test.codingwithclaude.dev → Static files (validation)
dashboard.test.codingwithclaude.dev → cwc-dashboard:3001
api.test.codingwithclaude.dev → cwc-api:5040
auth.test.codingwithclaude.dev → cwc-auth:5005
content.test.codingwithclaude.dev → cwc-content:5008
Internal IP /api/, /auth/, etc. → Backend services

Prod nginx routes:

api.codingwithclaude.dev → cwc-api:5040
auth.codingwithclaude.dev → cwc-auth:5005
content.codingwithclaude.dev → cwc-content:5008
dashboard.codingwithclaude.dev → cwc-dashboard:3001

CORS: nginx does NOT handle CORS headers. CORS is handled exclusively by Express middleware in the backend services (see cwc-backend-utils/CLAUDE.md). This prevents duplicate CORS headers which cause browsers to reject responses.

nginx Internal API Access (Test Only)

Path-based routing for internal API access via private network IP.

The default nginx server block (port 80, server_name _) provides path-based routing to backend services:

Path	Proxies To
`/auth/`	`cwc-auth:5005`
`/api/`	`cwc-api:5040`
`/content/`	`cwc-content:5008`
`/storage/`	`cwc-storage:5030`
`/data/`	`cwc-sql:5020`

Use case: CLI tools (like cwc-session-importer) can access test services via private network IP without DNS configuration:

# Instead of https://api.test.codingwithclaude.dev/api/v1
API_URI_EXTERNAL=http://172.16.0.6/api/v1

Benefits:

No firewall ports needed per service
No DNS subdomains required for internal access
Single entry point via nginx

SSL Certificate Management

Wildcard certificate for *.codingwithclaude.dev and *.test.codingwithclaude.dev using Let's Encrypt DNS-01 challenge (Cloudflare).

Script: deployment-scripts/renew-certs.sh

# Check and renew if needed (auto-called by deploy-nginx.sh)
./renew-certs.sh test

# Force renewal
./renew-certs.sh prod --force

# Test with Let's Encrypt staging server
./renew-certs.sh test --staging

# Dry run (no actual certs generated)
./renew-certs.sh test --dry-run

How it works:

Checks if certs exist on server at /home/devops/{env}-cwc-certs/
Checks expiry date (renews if < 30 days remaining)
Runs certbot DNS-01 challenge locally via Cloudflare API
Uploads fullchain.pem and privkey.pem to server
Reloads nginx if running

Certificate domains:

codingwithclaude.dev - Base domain
*.codingwithclaude.dev - First-level subdomains (test., api., etc.)
*.test.codingwithclaude.dev - Second-level subdomains (static.test., etc.)

Why *.test.codingwithclaude.dev? Wildcard certs only cover one level of subdomain. To support static.test.codingwithclaude.dev, we need an explicit wildcard for *.test.codingwithclaude.dev.

Prerequisites:

certbot + certbot-dns-cloudflare plugin installed locally (pip install certbot-dns-cloudflare)
Cloudflare API token at {secrets-path}/dns/cloudflare.ini:
```
dns_cloudflare_api_token = YOUR_API_TOKEN
```
Token needs Zone:DNS:Edit permission for the domain

Certificate paths:

Local: ~/cwc/private/cwc-certs/
Server: /home/devops/{env}-cwc-certs/

Integration: deploy-nginx.sh automatically calls renew-certs.sh before deployment.

Cloudflare Credentials

Two separate credential files for different purposes:

File	Format	Purpose
`{secrets-path}/dns/cloudflare.ini`	INI	certbot DNS-01 challenge
`{secrets-path}/cloudflare/credentials.json`	JSON	Wrangler (Cloudflare Pages publishing)

dns/cloudflare.ini (certbot format):

dns_cloudflare_api_token = YOUR_API_TOKEN

cloudflare/credentials.json (Wrangler format):

{
  "apiToken": "your-cloudflare-api-token",
  "accountId": "your-cloudflare-account-id"
}

Token permissions needed:

Zone:DNS:Edit - For DNS-01 certificate challenges
Cloudflare Pages:Edit - For publishing to Cloudflare Pages

Static Site DNS Configuration

Multi-level subdomains (e.g., static.test.codingwithclaude.dev) require special DNS configuration.

Cloudflare's free Universal SSL only covers single-level subdomains (*.codingwithclaude.dev), not multi-level (*.test.codingwithclaude.dev).

Solution: Set the DNS record to DNS only (gray cloud):

Traffic goes directly to the VPS
VPS nginx uses the Let's Encrypt wildcard cert (which includes *.test.codingwithclaude.dev)
Bypasses Cloudflare's proxy and SSL

Example: static.test.codingwithclaude.dev

Type: A record
Proxy status: DNS only (gray cloud)
Points to: VPS public IP

Test Environment Basic Auth (TEST ONLY)

CRITICAL: Basic auth is for TEST ENVIRONMENT ONLY. NEVER apply basic auth to production.

The test site (test.codingwithclaude.dev and static.test.codingwithclaude.dev) is protected with HTTP Basic Authentication to prevent public access during development.

Affected domains (test only):

test.codingwithclaude.dev - Main website (SSR)
static.test.codingwithclaude.dev - Static website (SSG validation)

NOT affected (remain publicly accessible):

api.test.codingwithclaude.dev - API endpoints (for local dev/tools)
auth.test.codingwithclaude.dev - Auth service
content.test.codingwithclaude.dev - Content service
dashboard.test.codingwithclaude.dev - Admin dashboard
All health check endpoints (/health)
.data files - React Router client-side navigation data
/__manifest endpoint - React Router route discovery (SSR only)

htpasswd file location:

{secrets-path}/deployment/nginx/test.htpasswd

Creating the htpasswd file:

# Create new htpasswd file with first user
htpasswd -c test.htpasswd username

# Add additional users (without -c flag)
htpasswd test.htpasswd another-user

How it works:

deploy-nginx.sh test copies test.htpasswd from secrets to the deployment archive
Docker mounts the file at /etc/nginx/htpasswd
nginx uses auth_basic_user_file /etc/nginx/htpasswd for protected server blocks

If htpasswd file is missing:

Build will show a warning but continue
nginx will start but return 500 errors for protected pages
Create the file and redeploy nginx to fix

Why .data and /__manifest are exempted:

React Router's client-side navigation uses fetch() to request .data files and /__manifest. These fetch requests don't automatically include HTTP Basic Auth credentials, causing 401 errors. Since these files contain the same data as the HTML pages (no security concern), they're exempted from auth.

Website Deployment: Runtime Dependencies

CRITICAL: Website SSR deployment reads dependencies from cwc-website/package.json.

The website/build.ts dynamically reads all dependencies from the actual package.json (excluding workspace:* dependencies which are bundled by Vite). This ensures new dependencies are automatically included without manual updates.

Previously, dependencies were hardcoded, causing "Cannot find package" errors when new packages were added.

Website Build: Docker Cache

The website-build uses --no-cache to prevent stale Docker layer issues.

Docker's build cache can become corrupted, causing errors like:

failed to prepare extraction snapshot: parent snapshot does not exist

Using --no-cache ensures reliable builds. Since website-build runs infrequently, reliability is more important than build speed.

Implementation Status

See CHECKLIST.md for current implementation progress.

packages/cwc-deployment/templates/nginx/conf.d/default.conf.prod.template

2 versions

Version 1

# ============================================
# PRODUCTION NGINX CONFIGURATION
# ============================================
# Main website hosted on Cloudflare Pages
# This nginx only handles API subdomains and dashboard
#
# SSL Configuration: Wildcard cert (*.codingwithclaude.dev)

# ============================================
# API SERVICE: api.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name api.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name api.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $api cwc-api;
        proxy_pass http://$api:5040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# AUTH SERVICE: auth.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name auth.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name auth.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    location / {
        # CORS headers for Cloudflare Pages
        add_header Access-Control-Allow-Origin "https://${BASE_DOMAIN}" always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
        add_header Access-Control-Allow-Credentials "true" always;

        # Handle preflight requests
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin "https://${BASE_DOMAIN}" always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
            add_header Access-Control-Allow-Credentials "true" always;
            add_header Access-Control-Max-Age 1728000;
            add_header Content-Type "text/plain charset=UTF-8";
            add_header Content-Length 0;
            return 204;
        }

        set $auth cwc-auth;
        proxy_pass http://$auth:5005;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# CONTENT SERVICE: content.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name content.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name content.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    location / {
        # CORS headers for Cloudflare Pages
        add_header Access-Control-Allow-Origin "https://${BASE_DOMAIN}" always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
        add_header Access-Control-Allow-Credentials "true" always;

        # Handle preflight requests
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin "https://${BASE_DOMAIN}" always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
            add_header Access-Control-Allow-Credentials "true" always;
            add_header Access-Control-Max-Age 1728000;
            add_header Content-Type "text/plain charset=UTF-8";
            add_header Content-Length 0;
            return 204;
        }

        set $content cwc-content;
        proxy_pass http://$content:5008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }
}

# ============================================
# ADMIN DASHBOARD: dashboard.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name dashboard.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name dashboard.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    location / {
        set $dashboard cwc-dashboard;
        proxy_pass http://$dashboard:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

Version 2 (latest)

# ============================================
# PRODUCTION NGINX CONFIGURATION
# ============================================
# Main website hosted on Cloudflare Pages
# This nginx only handles API subdomains and dashboard
#
# SSL Configuration: Wildcard cert (*.codingwithclaude.dev)

# ============================================
# API SERVICE: api.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name api.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name api.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $api cwc-api;
        proxy_pass http://$api:5040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# AUTH SERVICE: auth.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name auth.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name auth.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $auth cwc-auth;
        proxy_pass http://$auth:5005;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# CONTENT SERVICE: content.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name content.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name content.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $content cwc-content;
        proxy_pass http://$content:5008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }
}

# ============================================
# ADMIN DASHBOARD: dashboard.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name dashboard.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name dashboard.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    location / {
        set $dashboard cwc-dashboard;
        proxy_pass http://$dashboard:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

packages/cwc-deployment/templates/nginx/conf.d/default.conf.test.template

2 versions

Version 1

# ============================================
# SSL Configuration (Wildcard cert: *.codingwithclaude.dev)
# ============================================
# All domains use the same wildcard certificate

# ============================================
# INTERNAL API ACCESS (Private Network)
# ============================================
# Allows direct access to backend services via IP address
# Used by CLI tools (session-importer) and development
# Access: http://{server-ip}/auth/v1, /api/v1, /content/v1, etc.

server {
    listen 80 default_server;
    server_name _;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # Auth service: /auth/v1/*
    location /auth/ {
        set $auth cwc-auth;
        proxy_pass http://$auth:5005;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # API service: /api/v1/*
    location /api/ {
        set $api cwc-api;
        proxy_pass http://$api:5040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Content service: /content/v1/*
    location /content/ {
        set $content cwc-content;
        proxy_pass http://$content:5008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }

    # Storage service: /storage/v1/* (internal use)
    location /storage/ {
        set $storage cwc-storage;
        proxy_pass http://$storage:5030;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }

    # SQL service: /data/v1/* (internal use)
    location /data/ {
        set $sql cwc-sql;
        proxy_pass http://$sql:5020;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Block all other paths on direct IP access
    location / {
        return 404 "Use /auth/v1, /api/v1, /content/v1, /storage/v1, or /data/v1\n";
        add_header Content-Type text/plain;
    }
}

# ============================================
# API SERVICE: api.${BASE_DOMAIN}
# ============================================
# Enables local development and external tools to access cwc-api via subdomain
server {
    listen 80;
    server_name api.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name api.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $api cwc-api;
        proxy_pass http://$api:5040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# AUTH SERVICE: auth.${BASE_DOMAIN}
# ============================================
# Enables local development and external tools to access cwc-auth via subdomain
server {
    listen 80;
    server_name auth.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name auth.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    location / {
        # CORS headers for local development (allows any origin in test environment)
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
        add_header Access-Control-Allow-Credentials "true" always;

        # Handle preflight requests
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin $http_origin always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
            add_header Access-Control-Allow-Credentials "true" always;
            add_header Access-Control-Max-Age 1728000;
            add_header Content-Type "text/plain charset=UTF-8";
            add_header Content-Length 0;
            return 204;
        }

        set $auth cwc-auth;
        proxy_pass http://$auth:5005;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# CONTENT SERVICE: content.${BASE_DOMAIN}
# ============================================
# Enables local development and external tools to access cwc-content via subdomain
server {
    listen 80;
    server_name content.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name content.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    location / {
        # CORS headers for local development (allows any origin in test environment)
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
        add_header Access-Control-Allow-Credentials "true" always;

        # Handle preflight requests
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin $http_origin always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Allow-Headers "Authorization, Content-Type, X-Requested-With" always;
            add_header Access-Control-Allow-Credentials "true" always;
            add_header Access-Control-Max-Age 1728000;
            add_header Content-Type "text/plain charset=UTF-8";
            add_header Content-Length 0;
            return 204;
        }

        set $content cwc-content;
        proxy_pass http://$content:5008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }
}

# ============================================
# MAIN WEBSITE: ${BASE_DOMAIN}
# ============================================
# TEST ENVIRONMENT ONLY: Basic auth protection
# This prevents public access to the test site while allowing
# authorized reviewers to access it with credentials.
# NEVER apply basic auth to production - this is test-only.
# ============================================
server {
    listen 80;
    server_name ${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name ${BASE_DOMAIN};

    # Wildcard certificate covers all subdomains
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # ===========================================
    # TEST ONLY: Basic Authentication
    # Protects test site from public access.
    # htpasswd file is mounted at /etc/nginx/htpasswd
    # ===========================================
    auth_basic "CWC Test Environment";
    auth_basic_user_file /etc/nginx/htpasswd;

    # OCSP Stapling for better performance

    # Shared location blocks (health check)
    include /etc/nginx/conf.d/api-locations.inc;

    # React Router .data files (no auth - client-side fetches can't send credentials)
    # These contain the same data as the HTML pages, so no security concern
    location ~ \.data$ {
        auth_basic off;
        set $website cwc-website;
        proxy_pass http://$website:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Proxy all requests to cwc-website (React Router SSR)
    # Using variable defers DNS resolution to runtime (allows nginx to start without backend)
    location / {
        set $website cwc-website;
        proxy_pass http://$website:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

# ============================================
# STATIC WEBSITE (SSG): static.${BASE_DOMAIN}
# ============================================
# Serves pre-rendered static files from website-build
# Used to validate SSG output before deploying to Cloudflare Pages
# TEST ENVIRONMENT ONLY: Basic auth protection (same as main site)
# ============================================

server {
    listen 80;
    server_name static.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name static.${BASE_DOMAIN};

    # Wildcard certificate covers all subdomains
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # ===========================================
    # TEST ONLY: Basic Authentication
    # Protects test static site from public access.
    # htpasswd file is mounted at /etc/nginx/htpasswd
    # ===========================================
    auth_basic "CWC Test Environment";
    auth_basic_user_file /etc/nginx/htpasswd;

    root /var/www/static;
    index index.html;

    # Health check (no auth required for monitoring)
    location /health {
        auth_basic off;
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # React Router client-side navigation files (no auth - fetches can't send credentials)
    # .data files and __manifest contain the same data as HTML pages, so no security concern
    location ~ \.data$ {
        auth_basic off;
        try_files $uri =404;
    }

    location = /__manifest {
        auth_basic off;
        try_files $uri =404;
    }

    # Try static files, then fall back to index.html for SPA routing
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Cache HTML files for shorter duration
    location ~* \.html$ {
        expires 1h;
        add_header Cache-Control "public, must-revalidate";
    }
}

# ============================================
# ADMIN DASHBOARD: dashboard.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name dashboard.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name dashboard.${BASE_DOMAIN};

    # Same wildcard certificate
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Shared location blocks (health check)
    include /etc/nginx/conf.d/api-locations.inc;

    # Proxy all requests to cwc-dashboard
    # Using variable defers DNS resolution to runtime (allows nginx to start without backend)
    location / {
        set $dashboard cwc-dashboard;
        proxy_pass http://$dashboard:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

Version 2 (latest)

# ============================================
# SSL Configuration (Wildcard cert: *.codingwithclaude.dev)
# ============================================
# All domains use the same wildcard certificate

# ============================================
# INTERNAL API ACCESS (Private Network)
# ============================================
# Allows direct access to backend services via IP address
# Used by CLI tools (session-importer) and development
# Access: http://{server-ip}/auth/v1, /api/v1, /content/v1, etc.

server {
    listen 80 default_server;
    server_name _;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # Auth service: /auth/v1/*
    location /auth/ {
        set $auth cwc-auth;
        proxy_pass http://$auth:5005;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # API service: /api/v1/*
    location /api/ {
        set $api cwc-api;
        proxy_pass http://$api:5040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Content service: /content/v1/*
    location /content/ {
        set $content cwc-content;
        proxy_pass http://$content:5008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }

    # Storage service: /storage/v1/* (internal use)
    location /storage/ {
        set $storage cwc-storage;
        proxy_pass http://$storage:5030;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }

    # SQL service: /data/v1/* (internal use)
    location /data/ {
        set $sql cwc-sql;
        proxy_pass http://$sql:5020;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Block all other paths on direct IP access
    location / {
        return 404 "Use /auth/v1, /api/v1, /content/v1, /storage/v1, or /data/v1\n";
        add_header Content-Type text/plain;
    }
}

# ============================================
# API SERVICE: api.${BASE_DOMAIN}
# ============================================
# Enables local development and external tools to access cwc-api via subdomain
server {
    listen 80;
    server_name api.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name api.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $api cwc-api;
        proxy_pass http://$api:5040;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# AUTH SERVICE: auth.${BASE_DOMAIN}
# ============================================
# Enables local development and external tools to access cwc-auth via subdomain
server {
    listen 80;
    server_name auth.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name auth.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $auth cwc-auth;
        proxy_pass http://$auth:5005;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# ============================================
# CONTENT SERVICE: content.${BASE_DOMAIN}
# ============================================
# Enables local development and external tools to access cwc-content via subdomain
server {
    listen 80;
    server_name content.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name content.${BASE_DOMAIN};

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # Health check
    location /health {
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # CORS handled by Express middleware (see cwc-backend-utils/express/cors.ts)
    location / {
        set $content cwc-content;
        proxy_pass http://$content:5008;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 50m;
    }
}

# ============================================
# MAIN WEBSITE: ${BASE_DOMAIN}
# ============================================
# TEST ENVIRONMENT ONLY: Basic auth protection
# This prevents public access to the test site while allowing
# authorized reviewers to access it with credentials.
# NEVER apply basic auth to production - this is test-only.
# ============================================
server {
    listen 80;
    server_name ${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name ${BASE_DOMAIN};

    # Wildcard certificate covers all subdomains
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # ===========================================
    # TEST ONLY: Basic Authentication
    # Protects test site from public access.
    # htpasswd file is mounted at /etc/nginx/htpasswd
    # ===========================================
    auth_basic "CWC Test Environment";
    auth_basic_user_file /etc/nginx/htpasswd;

    # OCSP Stapling for better performance

    # Shared location blocks (health check)
    include /etc/nginx/conf.d/api-locations.inc;

    # React Router .data files (no auth - client-side fetches can't send credentials)
    # These contain the same data as the HTML pages, so no security concern
    location ~ \.data$ {
        auth_basic off;
        set $website cwc-website;
        proxy_pass http://$website:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Proxy all requests to cwc-website (React Router SSR)
    # Using variable defers DNS resolution to runtime (allows nginx to start without backend)
    location / {
        set $website cwc-website;
        proxy_pass http://$website:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

# ============================================
# STATIC WEBSITE (SSG): static.${BASE_DOMAIN}
# ============================================
# Serves pre-rendered static files from website-build
# Used to validate SSG output before deploying to Cloudflare Pages
# TEST ENVIRONMENT ONLY: Basic auth protection (same as main site)
# ============================================

server {
    listen 80;
    server_name static.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name static.${BASE_DOMAIN};

    # Wildcard certificate covers all subdomains
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # ===========================================
    # TEST ONLY: Basic Authentication
    # Protects test static site from public access.
    # htpasswd file is mounted at /etc/nginx/htpasswd
    # ===========================================
    auth_basic "CWC Test Environment";
    auth_basic_user_file /etc/nginx/htpasswd;

    root /var/www/static;
    index index.html;

    # Health check (no auth required for monitoring)
    location /health {
        auth_basic off;
        access_log off;
        return 200 "healthy\n";
        add_header Content-Type text/plain;
    }

    # React Router client-side navigation files (no auth - fetches can't send credentials)
    # .data files and __manifest contain the same data as HTML pages, so no security concern
    location ~ \.data$ {
        auth_basic off;
        try_files $uri =404;
    }

    location = /__manifest {
        auth_basic off;
        try_files $uri =404;
    }

    # Try static files, then fall back to index.html for SPA routing
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Cache HTML files for shorter duration
    location ~* \.html$ {
        expires 1h;
        add_header Cache-Control "public, must-revalidate";
    }
}

# ============================================
# ADMIN DASHBOARD: dashboard.${BASE_DOMAIN}
# ============================================
server {
    listen 80;
    server_name dashboard.${BASE_DOMAIN};
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    http2 on;
    server_name dashboard.${BASE_DOMAIN};

    # Same wildcard certificate
    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;


    # Shared location blocks (health check)
    include /etc/nginx/conf.d/api-locations.inc;

    # Proxy all requests to cwc-dashboard
    # Using variable defers DNS resolution to runtime (allows nginx to start without backend)
    location / {
        set $dashboard cwc-dashboard;
        proxy_pass http://$dashboard:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

packages/cwc-website/CLAUDE.md

2 versions

Version 1

cwc-website Package

Public-facing React Router v7 web application with SSG (Static Site Generation) for codingwithclaude.dev.

Technology Stack

React 19 - UI library
React Router v7 - Framework mode with SSG pre-rendering
Vite - Build tool
SCSS - Styling (colocated with layout templates)

Build Modes: SSR vs SSG

The website supports two deployment modes controlled by the SSG_BUILD environment variable:

Mode	SSG_BUILD	Pre-rendering	Use Case
SSR	not set	Disabled	`deploy-website.sh` - Fast builds, pages render on request
SSG	`true`	Enabled	`deploy-website-build.sh` - Static HTML, CDN hosting

SSR Mode (Default)

When SSG_BUILD is not set, the build skips pre-rendering entirely:

Pages render on each request (server-side)
No API access needed during build
Fast build times
Used by deploy-website.sh

SSG Mode

When SSG_BUILD=true, React Router pre-renders all routes to static HTML:

Requires API access during build
Generates pure static files in build/client/
Used by deploy-website-build.sh (sets SSG_BUILD=true automatically)
Disables fog of war route discovery for static deployments

Route Discovery: Fog of War (CRITICAL for SSG)

Problem: React Router v7's "fog of war" feature lazily discovers routes via /__manifest requests. This works for SSR but breaks SSG deployments because:

Static files have no server to respond to /__manifest
Client-side navigation fails with 404 errors

Solution: Disable fog of war for SSG builds in react-router.config.ts:

// Only pre-render when SSG_BUILD is set
const isSSGBuild = process.env['SSG_BUILD'] === 'true';

export default {
  ssr: true,

  // Disable lazy route discovery for SSG builds
  // All routes are included upfront in the client bundle
  routeDiscovery: isSSGBuild ? { mode: 'initial' } : undefined,

  // Pre-render only for SSG builds
  prerender: isSSGBuild ? discoverRoutes : false,
} satisfies Config;

What routeDiscovery: { mode: 'initial' } does:

Includes ALL routes in the initial client bundle (no lazy loading)
Prevents client-side requests to /__manifest
Required for any static deployment (Cloudflare Pages, nginx static, etc.)

Reference: https://github.com/remix-run/react-router/discussions/13241

Client-Side Navigation: .data Files

How React Router v7 client navigation works:

When users click links (client-side navigation), React Router fetches .data files instead of full HTML:

/project/foo → requests /project/foo.data (JSON with loader data)
Avoids full page reload, provides SPA-like experience

SSG output includes .data files:

build/client/
├── project/
│   └── foo/
│       ├── index.html    # Full HTML for initial/direct load
│       └── index.data    # JSON data for client-side navigation

Important for deployments:

.data files must be served with correct MIME type
If using HTTP Basic Auth (test env), .data requests bypass auth because fetch() doesn't send credentials automatically
See cwc-deployment CLAUDE.md for nginx configuration details

Static Site Generation (SSG)

The website uses React Router v7's pre-rendering feature to generate static HTML at build time.

How It Works

Build-time route discovery (src/prerender/) fetches all projects and sessions from the API
React Router pre-renders each route to static HTML + .data files
Output is pure static files in build/client/ - no server required for hosting

Build Requirements (SSG Only)

SSG builds require API access for:

Route discovery (API_URI_BUILD) - prerender function discovers all routes
Loader execution (API_URI_INTERNAL) - loaders fetch data for each route

# SSG build against test server (handled by deploy-website-build.sh)
SSG_BUILD=true \
API_URI_BUILD=http://172.16.0.6/api/v1 \
API_URI_INTERNAL=http://172.16.0.6/api/v1 \
pnpm build

Why two variables?

API_URI_BUILD - Used by src/prerender/ at config load time
API_URI_INTERNAL - Used by route loaders via loadConfig()

For convenience, set both to the same value when building.

Pagination in Route Discovery

The prerenderApi.ts uses pageSize: 1000 when fetching projects and sessions to ensure all routes are discovered. The API defaults to 20 results per page, which would miss routes if not overridden.

Pre-rendered Routes

Route	Discovery	View Type
`/`, `/about`, `/privacy-policy`	Static (automatic)	SSG
`/projects`	Static (hardcoded)	SSG
`/project/:projectId`	Dynamic (fetched from API)	SSG
`/session/:codingSessionPkId`	Dynamic (fetched from API)	SSG
`/session/:codingSessionPkId/page/:pageNumber`	Dynamic (calculated)	SSG
`/session-editor/:codingSessionPkId`	Not pre-rendered	Client-side

Build Output

build/client/
├── index.html                    # / route
├── about/index.html              # /about route
├── privacy-policy/index.html     # /privacy-policy route
├── projects/index.html           # /projects route
├── project/
│   └── {projectId}/
│       └── index.html            # /project/:projectId
├── session/
│   └── {codingSessionPkId}/
│       ├── index.html            # /session/:codingSessionPkId
│       └── page/
│           └── {pageNumber}/
│               └── index.html    # /session/:codingSessionPkId/page/:pageNumber
└── assets/                       # JS, CSS bundles

Deployment

The build/client/ directory contains all static files. Deploy to any static hosting:

# Cloudflare Pages (example)
wrangler pages deploy build/client --project-name=codingwithclaude

Critical Naming Rules

1. Avoid Plurals

Use singular entity names for files and variables:

// CORRECT
project.ts
codingSession.ts
userProfile.ts

// INCORRECT
projects.ts
codingSessions.ts
userProfiles.ts

2. Consistent Entity Names

Use the exact entity name from cwc-types throughout the codebase. No abbreviations, no variants:

Entity	Correct	Incorrect
CodingSession	`CodingSession`, `codingSession`	`session`, `code-session`, `codeSession`, `Session`
Project	`Project`, `project`	`proj`, `prj`
UserProfile	`UserProfile`, `userProfile`	`user`, `profile`, `User`

3. No Naming Variants

Pick one form and use it everywhere:

PascalCase for React components and component folders
camelCase for non-component files and variables

4. Qualified Component Names

When components belong to a layout, prefix them with the layout name:

// SiteLayout components
SiteHeader.tsx
SiteFooter.tsx
SiteMenu.tsx

// ProjectLayout components (future)
ProjectHeader.tsx
ProjectSidebar.tsx

Directory Structure

src/
├── entry.client.tsx    # React Router v7 client entry (framework convention)
├── entry.server.tsx    # React Router v7 SSR entry (framework convention)
├── root.tsx            # HTML shell (framework convention)
├── routes.ts           # Route configuration (framework convention)
├── views/              # Page/view components (PascalCase folders)
│   └── Home/
│       ├── Home.tsx
│       └── index.ts
├── layouts/            # Layout templates with colocated SCSS
│   └── SiteLayout/
│       ├── SiteLayout.tsx
│       ├── SiteHeader.tsx
│       ├── SiteFooter.tsx
│       ├── SiteMenu.tsx
│       ├── index.ts
│       └── styles/     # SCSS ported from html5up-phantom
│           ├── main.scss
│           ├── libs/
│           ├── base/
│           ├── components/
│           └── layout/
├── components/         # Shared/reusable components (flat for now)
├── hooks/              # Global hooks
│   ├── useMenu.tsx
│   └── index.ts
├── prerender/          # Build-time route discovery for SSG
│   ├── prerender.ts    # Main route discovery function
│   ├── prerenderApi.ts # Build-time API client
│   └── index.ts        # Barrel export
├── server/             # Server-only data fetching (by entity)
│   ├── project.ts
│   └── codingSession.ts
└── config/
    └── config.types.ts

Framework Convention Files

Files at src/ root follow React Router v7 framework conventions and cannot be renamed or relocated:

File	Purpose
`entry.client.tsx`	Client-side hydration entry point
`entry.server.tsx`	SSR rendering entry point
`root.tsx`	HTML shell (`<html>`, `<head>`, `<body>`)
`routes.ts`	Route configuration

File Naming Conventions

File Type	Convention	Example
React component	PascalCase	`Home.tsx`, `SiteLayout.tsx`
Component folder	PascalCase	`Home/`, `SiteLayout/`
Hook	`use` + PascalCase, `.tsx` if renders UI	`useMenu.tsx`
Server file	camelCase by entity	`project.ts`, `codingSession.ts`
Config/utility	camelCase	`routes.ts`, `config.types.ts`
SCSS partial	`_` prefix	`_vars.scss`, `_typography.scss`
SCSS entry	`main.scss`	`main.scss`
Barrel export	`index.ts`	`index.ts`

View Structure

Each view folder contains:

views/Home/
├── Home.tsx      # Main view component
├── index.ts      # Barrel export
└── [optional]    # View-specific components if needed

View-specific components live in the view folder, not in components/.

Layout Structure

Each layout folder contains components and colocated SCSS:

layouts/SiteLayout/
├── SiteLayout.tsx      # Main layout wrapper (must have default export)
├── SiteHeader.tsx      # Layout-specific component
├── SiteFooter.tsx      # Layout-specific component
├── SiteMenu.tsx        # Layout-specific component
├── index.ts            # Barrel export
└── styles/             # Colocated SCSS (ported from html5up-phantom)
    ├── main.scss       # Entry point, imports all partials
    ├── ATTRIBUTION.md  # CC BY 3.0 license attribution
    ├── libs/           # Variables, functions, mixins, breakpoints
    ├── base/           # Reset, page, typography
    ├── components/     # Tiles, buttons, forms, etc.
    └── layout/         # Header, menu, main, footer, wrapper

CRITICAL: Route modules (including layouts) must have a default export for React Router v7 to use them. Named exports alone will not work.

Data Fetching

Loader Pattern (React Router v7)

Data fetching happens in route loaders (server-side):

// In routes.ts
import { route } from '@react-router/dev/routes';

export default [
  route('project/:projectId', 'views/Project/Project.tsx'),
];

// In views/Project/Project.tsx
import type { Route } from './+types/Project';

export async function loader({ params }: Route.LoaderArgs) {
  // Fetch from cwc-api
  const project = await getProject(params.projectId);
  return { project };
}

export default function Project({ loaderData }: Route.ComponentProps) {
  const { project } = loaderData;
  return <div>{project.name}</div>;
}

Server Files Organization

Server files are organized by entity (singular):

server/
├── project.ts        # getProject, getProjectList
├── codingSession.ts  # getCodingSession, getCodingSessionContent
└── index.ts          # Re-exports

Scripts

pnpm website dev       # Start dev server
pnpm website build     # Production build
pnpm website start     # Start production server
pnpm website typecheck # Type check

Environment Variables

Variable	Description
`APP_URL`	Public website URL
`API_URI`	cwc-api service URL
`CONTENT_URI`	cwc-content service URL

What to Check During Planning

Entity naming - Using exact names from cwc-types?
File naming - Following conventions (no plurals, correct case)?
Component location - View-specific in views/, shared in components/?
SCSS location - Colocated with layout?
Data fetching - Using loader pattern?

Version 2 (latest)

cwc-website Package

Public-facing React Router v7 web application with SSG (Static Site Generation) for codingwithclaude.dev.

Technology Stack

React 19 - UI library
React Router v7 - Framework mode with SSG pre-rendering
Vite - Build tool
SCSS - Styling (colocated with layout templates)

Build Modes: SSR vs SSG

The website supports two deployment modes controlled by the SSG_BUILD environment variable:

Mode	SSG_BUILD	Pre-rendering	Use Case
SSR	not set	Disabled	`deploy-website.sh` - Fast builds, pages render on request
SSG	`true`	Enabled	`deploy-website-build.sh` - Static HTML, CDN hosting

SSR Mode (Default)

When SSG_BUILD is not set, the build skips pre-rendering entirely:

Pages render on each request (server-side)
No API access needed during build
Fast build times
Used by deploy-website.sh

SSG Mode

When SSG_BUILD=true, React Router pre-renders all routes to static HTML:

Requires API access during build
Generates pure static files in build/client/
Used by deploy-website-build.sh (sets SSG_BUILD=true automatically)
Disables fog of war route discovery for static deployments

Route Discovery: Fog of War (CRITICAL for SSG)

Problem: React Router v7's "fog of war" feature lazily discovers routes via /__manifest requests. This works for SSR but breaks SSG deployments because:

Static files have no server to respond to /__manifest
Client-side navigation fails with 404 errors

Solution: Disable fog of war for SSG builds in react-router.config.ts:

// Only pre-render when SSG_BUILD is set
const isSSGBuild = process.env['SSG_BUILD'] === 'true';

export default {
  ssr: true,

  // Disable lazy route discovery for SSG builds
  // All routes are included upfront in the client bundle
  routeDiscovery: isSSGBuild ? { mode: 'initial' } : undefined,

  // Pre-render only for SSG builds
  prerender: isSSGBuild ? discoverRoutes : false,
} satisfies Config;

What routeDiscovery: { mode: 'initial' } does:

Includes ALL routes in the initial client bundle (no lazy loading)
Prevents client-side requests to /__manifest
Required for any static deployment (Cloudflare Pages, nginx static, etc.)

Reference: https://github.com/remix-run/react-router/discussions/13241

Client-Side Navigation: .data Files

How React Router v7 client navigation works:

When users click links (client-side navigation), React Router fetches .data files instead of full HTML:

/project/foo → requests /project/foo.data (JSON with loader data)
Avoids full page reload, provides SPA-like experience

SSG output includes .data files:

build/client/
├── project/
│   └── foo/
│       ├── index.html    # Full HTML for initial/direct load
│       └── index.data    # JSON data for client-side navigation

Important for deployments:

.data files must be served with correct MIME type
If using HTTP Basic Auth (test env), .data requests bypass auth because fetch() doesn't send credentials automatically
See cwc-deployment CLAUDE.md for nginx configuration details

Static Site Generation (SSG)

The website uses React Router v7's pre-rendering feature to generate static HTML at build time.

How It Works

Build-time route discovery (src/prerender/) fetches all projects and sessions from the API
React Router pre-renders each route to static HTML + .data files
Output is pure static files in build/client/ - no server required for hosting

Build Requirements (SSG Only)

SSG builds require API access for:

Route discovery (API_URI_BUILD) - prerender function discovers all routes
Loader execution (API_URI_INTERNAL) - loaders fetch data for each route

# SSG build against test server (handled by deploy-website-build.sh)
SSG_BUILD=true \
API_URI_BUILD=http://172.16.0.6/api/v1 \
API_URI_INTERNAL=http://172.16.0.6/api/v1 \
pnpm build

Why two variables?

API_URI_BUILD - Used by src/prerender/ at config load time
API_URI_INTERNAL - Used by route loaders via loadConfig()

For convenience, set both to the same value when building.

Pagination in Route Discovery

Pre-rendered Routes

Route	Discovery	View Type
`/`, `/about`, `/privacy-policy`	Static (automatic)	SSG
`/projects`	Static (hardcoded)	SSG
`/project/:projectId`	Dynamic (fetched from API)	SSG
`/session/:codingSessionPkId`	Dynamic (fetched from API)	SSG
`/session/:codingSessionPkId/page/:pageNumber`	Dynamic (calculated)	SSG
`/session-editor/:codingSessionPkId`	Not pre-rendered	Client-side

Build Output

build/client/
├── index.html                    # / route
├── about/index.html              # /about route
├── privacy-policy/index.html     # /privacy-policy route
├── projects/index.html           # /projects route
├── project/
│   └── {projectId}/
│       └── index.html            # /project/:projectId
├── session/
│   └── {codingSessionPkId}/
│       ├── index.html            # /session/:codingSessionPkId
│       └── page/
│           └── {pageNumber}/
│               └── index.html    # /session/:codingSessionPkId/page/:pageNumber
└── assets/                       # JS, CSS bundles

Deployment

The build/client/ directory contains all static files. Deploy to any static hosting:

# Cloudflare Pages (example)
wrangler pages deploy build/client --project-name=codingwithclaude

URL Architecture (Session 045)

Simplified Session URLs

Session URLs use codingSessionPkId (integer primary key) instead of the verbose UUID-based paths:

Old URL	New URL
`/project/myapp/session/7e6a848a-f0e0-4a10-83e0-495e287003f8`	`/session/42`
`/project/myapp/session/7e6a848a-.../page/2`	`/session/42/page/2`
`/project/myapp/session/7e6a848a-.../edit`	`/session-editor/42`

Rationale:

Cleaner URLs: /session/42 is more readable and shareable
No redundancy: Project info is derived from session.projectPkId - no need in URL
Globally unique: codingSessionPkId is unique across all projects
Consistent identifiers: All session operations use codingSessionPkId

SSG vs Client-Side Views

The website uses two types of views:

View Type	Auth Required	Pre-rendered	Example
SSG (Server)	No	Yes	`/session/42`, `/project/myapp`
Client-Side	Yes	No	`/session-editor/42`

SSG Views (views/server/):

Pre-rendered at build time to static HTML
Loader fetches data during build
Public content, no authentication
Located in views/server/ directory

Client-Side Views (views/client/):

Rendered in browser after page load
Fetches data via clientApi after mount
Requires user authentication
Located in views/client/ directory

Project Context Derivation

When loading /session/42:

Fetch session by codingSessionPkId = 42
Extract projectPkId from session response
Fetch project using getProjectByPkId(session.projectPkId)
No projectId needed in URL

Critical Naming Rules

1. Avoid Plurals

Use singular entity names for files and variables:

// CORRECT
project.ts
codingSession.ts
userProfile.ts

// INCORRECT
projects.ts
codingSessions.ts
userProfiles.ts

2. Consistent Entity Names

Use the exact entity name from cwc-types throughout the codebase. No abbreviations, no variants:

Entity	Correct	Incorrect
CodingSession	`CodingSession`, `codingSession`	`session`, `code-session`, `codeSession`, `Session`
Project	`Project`, `project`	`proj`, `prj`
UserProfile	`UserProfile`, `userProfile`	`user`, `profile`, `User`

3. No Naming Variants

Pick one form and use it everywhere:

PascalCase for React components and component folders
camelCase for non-component files and variables

4. Qualified Component Names

When components belong to a layout, prefix them with the layout name:

// SiteLayout components
SiteHeader.tsx
SiteFooter.tsx
SiteMenu.tsx

// ProjectLayout components (future)
ProjectHeader.tsx
ProjectSidebar.tsx

Directory Structure

src/
├── entry.client.tsx    # React Router v7 client entry (framework convention)
├── entry.server.tsx    # React Router v7 SSR entry (framework convention)
├── root.tsx            # HTML shell (framework convention)
├── routes.ts           # Route configuration (framework convention)
├── views/              # Page/view components (PascalCase folders)
│   └── Home/
│       ├── Home.tsx
│       └── index.ts
├── layouts/            # Layout templates with colocated SCSS
│   └── SiteLayout/
│       ├── SiteLayout.tsx
│       ├── SiteHeader.tsx
│       ├── SiteFooter.tsx
│       ├── SiteMenu.tsx
│       ├── index.ts
│       └── styles/     # SCSS ported from html5up-phantom
│           ├── main.scss
│           ├── libs/
│           ├── base/
│           ├── components/
│           └── layout/
├── components/         # Shared/reusable components (flat for now)
├── hooks/              # Global hooks
│   ├── useMenu.tsx
│   └── index.ts
├── prerender/          # Build-time route discovery for SSG
│   ├── prerender.ts    # Main route discovery function
│   ├── prerenderApi.ts # Build-time API client
│   └── index.ts        # Barrel export
├── server/             # Server-only data fetching (by entity)
│   ├── project.ts
│   └── codingSession.ts
└── config/
    └── config.types.ts

Framework Convention Files

Files at src/ root follow React Router v7 framework conventions and cannot be renamed or relocated:

File	Purpose
`entry.client.tsx`	Client-side hydration entry point
`entry.server.tsx`	SSR rendering entry point
`root.tsx`	HTML shell (`<html>`, `<head>`, `<body>`)
`routes.ts`	Route configuration

File Naming Conventions

File Type	Convention	Example
React component	PascalCase	`Home.tsx`, `SiteLayout.tsx`
Component folder	PascalCase	`Home/`, `SiteLayout/`
Hook	`use` + PascalCase, `.tsx` if renders UI	`useMenu.tsx`
Server file	camelCase by entity	`project.ts`, `codingSession.ts`
Config/utility	camelCase	`routes.ts`, `config.types.ts`
SCSS partial	`_` prefix	`_vars.scss`, `_typography.scss`
SCSS entry	`main.scss`	`main.scss`
Barrel export	`index.ts`	`index.ts`

View Structure

Each view folder contains:

views/Home/
├── Home.tsx      # Main view component
├── index.ts      # Barrel export
└── [optional]    # View-specific components if needed

View-specific components live in the view folder, not in components/.

Layout Structure

Each layout folder contains components and colocated SCSS:

layouts/SiteLayout/
├── SiteLayout.tsx      # Main layout wrapper (must have default export)
├── SiteHeader.tsx      # Layout-specific component
├── SiteFooter.tsx      # Layout-specific component
├── SiteMenu.tsx        # Layout-specific component
├── index.ts            # Barrel export
└── styles/             # Colocated SCSS (ported from html5up-phantom)
    ├── main.scss       # Entry point, imports all partials
    ├── ATTRIBUTION.md  # CC BY 3.0 license attribution
    ├── libs/           # Variables, functions, mixins, breakpoints
    ├── base/           # Reset, page, typography
    ├── components/     # Tiles, buttons, forms, etc.
    └── layout/         # Header, menu, main, footer, wrapper

CRITICAL: Route modules (including layouts) must have a default export for React Router v7 to use them. Named exports alone will not work.

Data Fetching

Loader Pattern (React Router v7)

Data fetching happens in route loaders (server-side):

// In routes.ts
import { route } from '@react-router/dev/routes';

export default [
  route('project/:projectId', 'views/Project/Project.tsx'),
];

// In views/Project/Project.tsx
import type { Route } from './+types/Project';

export async function loader({ params }: Route.LoaderArgs) {
  // Fetch from cwc-api
  const project = await getProject(params.projectId);
  return { project };
}

export default function Project({ loaderData }: Route.ComponentProps) {
  const { project } = loaderData;
  return <div>{project.name}</div>;
}

Server Files Organization

Server files are organized by entity (singular):

server/
├── project.ts        # getProject, getProjectList
├── codingSession.ts  # getCodingSession, getCodingSessionContent
└── index.ts          # Re-exports

Scripts

pnpm website dev       # Start dev server
pnpm website build     # Production build
pnpm website start     # Start production server
pnpm website typecheck # Type check

Environment Variables

Variable	Description
`APP_URL`	Public website URL
`API_URI`	cwc-api service URL
`CONTENT_URI`	cwc-content service URL

What to Check During Planning

Entity naming - Using exact names from cwc-types?
File naming - Following conventions (no plurals, correct case)?
Component location - View-specific in views/, shared in components/?
SCSS location - Colocated with layout?
Data fetching - Using loader pattern?

packages/cwc-website/jest.config.js

/** @type {import('jest').Config} */
export default {
  preset: 'ts-jest/presets/default-esm',
  testEnvironment: 'jsdom',
  extensionsToTreatAsEsm: ['.ts', '.tsx'],
  moduleNameMapper: {
    // Handle path aliases (must match tsconfig.json paths)
    '^@/(.*)$': '<rootDir>/src/$1',
    // Mock CSS/SCSS imports
    '\\.(css|scss|sass)$': '<rootDir>/src/__tests__/mocks/styleMock.ts',
    // Strip .js extensions from imports
    '^(\\.{1,2}/.*)\\.js$': '$1',
  },
  transform: {
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        useESM: true,
        tsconfig: {
          module: 'ES2022',
          moduleResolution: 'bundler',
          jsx: 'react-jsx',
        },
      },
    ],
  },
  testMatch: ['**/__tests__/**/*.test.ts', '**/__tests__/**/*.test.tsx', '**/*.test.ts', '**/*.test.tsx'],
  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
  collectCoverageFrom: [
    'src/**/*.{ts,tsx}',
    '!src/**/*.d.ts',
    '!src/entry.*.tsx',
    '!src/root.tsx',
    '!src/routes.ts',
    // Exclude server-side code from coverage for now
    '!src/server/**',
    '!src/prerender/**',
    '!src/config/**',
  ],
  coverageThreshold: {
    global: {
      branches: 50,
      functions: 50,
      lines: 50,
      statements: 50,
    },
  },
  // Ignore node_modules except for workspace packages
  transformIgnorePatterns: [
    'node_modules/(?!(cwc-types|cwc-utils|cwc-schema)/)',
  ],
};

packages/cwc-website/package.json

{
  "name": "cwc-website",
  "version": "1.0.0",
  "description": "Public-facing website for codingwithclaude.dev",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "RUNTIME_ENVIRONMENT=dev react-router dev",
    "build": "react-router build",
    "start": "react-router-serve ./build/server/index.js",
    "typecheck": "react-router typegen && tsc --noEmit",
    "test": "RUNTIME_ENVIRONMENT=unit node --experimental-vm-modules node_modules/jest/bin/jest.js"
  },
  "keywords": [
    "cwc"
  ],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "@radix-ui/react-dialog": "^1.1.15",
    "@radix-ui/react-navigation-menu": "^1.2.14",
    "@radix-ui/react-scroll-area": "^1.2.10",
    "@radix-ui/react-separator": "^1.1.8",
    "@radix-ui/react-slot": "^1.2.4",
    "@react-router/node": "^7.1.1",
    "@react-router/serve": "^7.1.1",
    "@tailwindcss/vite": "^4.1.18",
    "@tanstack/react-table": "^8.21.3",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "cwc-types": "workspace:*",
    "diff": "^8.0.2",
    "diff2html": "^3.4.55",
    "isbot": "^5.1.17",
    "isomorphic-dompurify": "^2.35.0",
    "lucide-react": "^0.562.0",
    "marked": "^17.0.1",
    "pako": "^2.1.0",
    "prismjs": "^1.30.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "react-resizable-panels": "^4.2.0",
    "react-router": "^7.1.1",
    "tailwind-merge": "^3.4.0"
  },
  "devDependencies": {
    "@jest/globals": "30",
    "@react-router/dev": "^7.1.1",
    "@testing-library/jest-dom": "^6.9.1",
    "@testing-library/react": "^16.3.1",
    "@testing-library/user-event": "^14.6.1",
    "@types/diff": "^8.0.0",
    "@types/jest": "30",
    "@types/node": "^22.0.0",
    "@types/pako": "^2.0.4",
    "@types/prismjs": "^1.26.5",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "@vitejs/plugin-react": "^4.3.4",
    "jest": "30",
    "jest-environment-jsdom": "^30.2.0",
    "tailwindcss": "^4.1.18",
    "ts-jest": "29",
    "tw-animate-css": "^1.4.0",
    "typescript": "^5.4.0",
    "vite": "^6.0.0"
  }
}

packages/cwc-website/src/__tests__/jest.d.ts

/**
 * Type declarations for Jest with @testing-library/jest-dom
 */

import '@testing-library/jest-dom';

// Extend Jest matchers with jest-dom types
declare global {
  namespace jest {
    interface Matchers<R> {
      toBeInTheDocument(): R;
      toBeVisible(): R;
      toBeEmpty(): R;
      toBeDisabled(): R;
      toBeEnabled(): R;
      toBeInvalid(): R;
      toBeRequired(): R;
      toBeValid(): R;
      toContainElement(element: HTMLElement | null): R;
      toContainHTML(htmlText: string): R;
      toHaveAttribute(attr: string, value?: string): R;
      toHaveClass(...classNames: string[]): R;
      toHaveFocus(): R;
      toHaveFormValues(expectedValues: Record<string, unknown>): R;
      toHaveStyle(css: string | Record<string, unknown>): R;
      toHaveTextContent(text: string | RegExp, options?: { normalizeWhitespace: boolean }): R;
      toHaveValue(value: string | string[] | number | null): R;
      toHaveDisplayValue(value: string | RegExp | Array<string | RegExp>): R;
      toBeChecked(): R;
      toBePartiallyChecked(): R;
      toHaveDescription(text?: string | RegExp): R;
      toHaveErrorMessage(text?: string | RegExp): R;
      toHaveAccessibleDescription(text?: string | RegExp): R;
      toHaveAccessibleName(text?: string | RegExp): R;
    }
  }
}

export {};

packages/cwc-website/src/__tests__/mocks/entities.mock.ts

3 versions

Version 1

/**
 * Mock entity factories for test data
 *
 * Provides factory functions for creating properly-typed test entities.
 * Use Partial<T> pattern with required base fields.
 */

import type { CwcCodingSession, CwcSessionData, CwcUser } from 'cwc-types';

/**
 * Create a mock CodingSession with all required fields
 */
export function createMockCodingSession(overrides?: Partial<CwcCodingSession>): CwcCodingSession {
  return {
    codingSessionPkId: 1,
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    userPkId: 1,
    projectPkId: 1,
    description: 'Test session',
    published: true,
    sessionId: 'session-001',
    storageKey: 'session-001.json.gz',
    startTimestamp: '2024-01-01T00:00:00Z',
    endTimestamp: '2024-01-01T01:00:00Z',
    gitBranch: 'main',
    model: 'claude-3-opus',
    messageCount: 10,
    filesModifiedCount: 5,
    ...overrides,
  };
}

/**
 * Create a mock SessionData with all required fields
 */
export function createMockSessionData(overrides?: Partial<CwcSessionData>): CwcSessionData {
  return {
    formatVersion: '1.0.0',
    sessionId: 'session-001',
    projectSessionFolder: 'coding-with-claude',
    startTimestamp: '2024-01-01T00:00:00.000Z',
    endTimestamp: '2024-01-01T01:00:00.000Z',
    model: 'claude-3-opus',
    gitBranch: 'main',
    summary: 'Test summary',
    cwd: '/path/to/project',
    claudeCodeVersion: '2.0.42',
    messages: [],
    files: [],
    stats: {
      totalMessages: 10,
      userMessages: 5,
      assistantMessages: 5,
      filesModified: 3,
      totalTokens: { input: 1000, output: 2000, cacheRead: 0, cacheCreation: 0 },
    },
    ...overrides,
  };
}

/**
 * Create a mock User with all required fields
 */
export function createMockUser(overrides?: Partial<CwcUser>): CwcUser {
  return {
    userPkId: 1,
    username: 'testuser',
    email: 'testuser@example.com',
    displayName: 'Test User',
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    loginType: 'cwc',
    passwordHash: 'hashed',
    emailVerified: true,
    ...overrides,
  };
}

Version 2

/**
 * Mock entity factories for test data
 *
 * Provides factory functions for creating properly-typed test entities.
 * Use Partial<T> pattern with required base fields.
 */

import type { CwcCodingSession, CwcSessionData, CwcUser } from 'cwc-types';

/**
 * Create a mock CodingSession with all required fields
 */
export function createMockCodingSession(overrides?: Partial<CwcCodingSession>): CwcCodingSession {
  return {
    codingSessionPkId: 1,
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    userPkId: 1,
    projectPkId: 1,
    description: 'Test session',
    published: true,
    sessionId: 'session-001',
    storageKey: 'session-001.json.gz',
    startTimestamp: '2024-01-01T00:00:00Z',
    endTimestamp: '2024-01-01T01:00:00Z',
    gitBranch: 'main',
    model: 'claude-3-opus',
    messageCount: 10,
    filesModifiedCount: 5,
    ...overrides,
  };
}

/**
 * Create a mock SessionData with all required fields
 */
export function createMockSessionData(overrides?: Partial<CwcSessionData>): CwcSessionData {
  return {
    formatVersion: '1.0.0',
    sessionId: 'session-001',
    projectSessionFolder: 'coding-with-claude',
    startTimestamp: '2024-01-01T00:00:00.000Z',
    endTimestamp: '2024-01-01T01:00:00.000Z',
    model: 'claude-3-opus',
    gitBranch: 'main',
    summary: 'Test summary',
    cwd: '/path/to/project',
    claudeCodeVersion: '2.0.42',
    messages: [],
    files: [],
    stats: {
      totalMessages: 10,
      userMessages: 5,
      assistantMessages: 5,
      filesModified: 3,
      totalTokens: { input: 1000, output: 2000, cacheRead: 0, cacheCreation: 0 },
    },
    ...overrides,
  };
}

/**
 * Create a mock User with all required fields
 */
export function createMockUser(overrides?: Partial<CwcUser>): CwcUser {
  return {
    userPkId: 1,
    username: 'testuser',
    email: 'testuser@example.com',
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    loginType: 'cwc',
    loginDate: '2024-01-01T00:00:00Z',
    password: 'hashed-password',
    emailConfirmed: true,
    deviceId: 'test-device-id',
    otpValidated: false,
    ...overrides,
  };
}

Version 3 (latest)

/**
 * Mock entity factories for test data
 *
 * Provides factory functions for creating properly-typed test entities.
 * Use Partial<T> pattern with required base fields.
 */

import type { CwcCodingSession, CwcProject, CwcSessionData, CwcUser } from 'cwc-types';

/**
 * Create a mock CodingSession with all required fields
 */
export function createMockCodingSession(overrides?: Partial<CwcCodingSession>): CwcCodingSession {
  return {
    codingSessionPkId: 1,
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    userPkId: 1,
    projectPkId: 1,
    description: 'Test session',
    published: true,
    sessionId: 'session-001',
    storageKey: 'session-001.json.gz',
    startTimestamp: '2024-01-01T00:00:00Z',
    endTimestamp: '2024-01-01T01:00:00Z',
    gitBranch: 'main',
    model: 'claude-3-opus',
    messageCount: 10,
    filesModifiedCount: 5,
    ...overrides,
  };
}

/**
 * Create a mock SessionData with all required fields
 */
export function createMockSessionData(overrides?: Partial<CwcSessionData>): CwcSessionData {
  return {
    formatVersion: '1.0.0',
    sessionId: 'session-001',
    projectSessionFolder: 'coding-with-claude',
    startTimestamp: '2024-01-01T00:00:00.000Z',
    endTimestamp: '2024-01-01T01:00:00.000Z',
    model: 'claude-3-opus',
    gitBranch: 'main',
    summary: 'Test summary',
    cwd: '/path/to/project',
    claudeCodeVersion: '2.0.42',
    messages: [],
    files: [],
    stats: {
      totalMessages: 10,
      userMessages: 5,
      assistantMessages: 5,
      filesModified: 3,
      totalTokens: { input: 1000, output: 2000, cacheRead: 0, cacheCreation: 0 },
    },
    ...overrides,
  };
}

/**
 * Create a mock User with all required fields
 */
export function createMockUser(overrides?: Partial<CwcUser>): CwcUser {
  return {
    userPkId: 1,
    username: 'testuser',
    email: 'testuser@example.com',
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    loginType: 'cwc',
    loginDate: '2024-01-01T00:00:00Z',
    password: 'hashed-password',
    emailConfirmed: true,
    deviceId: 'test-device-id',
    otpValidated: false,
    ...overrides,
  };
}

/**
 * Create a mock Project with all required fields
 */
export function createMockProject(overrides?: Partial<CwcProject>): CwcProject {
  return {
    projectPkId: 1,
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    userPkId: 1,
    projectId: 'coding-with-claude',
    projectSessionFolder: 'coding-with-claude',
    projectType: 'web',
    ...overrides,
  };
}

packages/cwc-website/src/__tests__/mocks/hooks.mock.ts

3 versions

Version 1

/**
 * Mocks for cwc-website hooks
 *
 * Provides mock implementations of useAuth, useConfig, etc.
 */

import type { CwcLogin } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';

// Default mock login (guest user)
export const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

// Authenticated user login
export function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mock auth context
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;

export const mockSetLoginFromJwt = jest.fn((jwt: string) => {
  if (jwt) {
    mockLogin = createMockAuthenticatedLogin({ authToken: jwt });
    mockIsAuthenticated = true;
    return true;
  }
  return false;
});

export const mockLogoff = jest.fn(() => {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
});

export function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

export function resetMockAuth(): void {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockSetLoginFromJwt.mockClear();
  mockLogoff.mockClear();
}

// Mock config
export const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

export function createMockConfig(overrides?: Partial<CwcWebsiteConfig>): CwcWebsiteConfig {
  return {
    ...mockConfig,
    ...overrides,
  };
}

// Jest mock implementations
jest.mock('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: mockSetLoginFromJwt,
    logoff: mockLogoff,
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
  AuthProvider: ({ children }: { children: React.ReactNode }) => children,
  ThemeProvider: ({ children }: { children: React.ReactNode }) => children,
}));

Version 2

/**
 * Mocks for cwc-website hooks
 *
 * Provides mock implementations of useAuth, useConfig, etc.
 */

import { jest } from '@jest/globals';
import type { CwcLogin } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';

// Default mock login (guest user)
export const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

// Authenticated user login
export function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mock auth context state
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;

// Export setters so tests can change the state
export function setMockLoginState(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

export const mockSetLoginFromJwt = jest.fn((jwt: string) => {
  if (jwt) {
    mockLogin = createMockAuthenticatedLogin({ authToken: jwt });
    mockIsAuthenticated = true;
    return true;
  }
  return false;
});

export const mockLogoff = jest.fn(() => {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
});

export function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

export function resetMockAuth(): void {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockSetLoginFromJwt.mockClear();
  mockLogoff.mockClear();
}

// Mock config
export const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

export function createMockConfig(overrides?: Partial<CwcWebsiteConfig>): CwcWebsiteConfig {
  return {
    ...mockConfig,
    ...overrides,
  };
}

// Jest mock implementations
jest.mock('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: mockSetLoginFromJwt,
    logoff: mockLogoff,
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
  AuthProvider: ({ children }: { children: React.ReactNode }) => children,
  ThemeProvider: ({ children }: { children: React.ReactNode }) => children,
}));

Version 3 (latest)

/**
 * Mock data for cwc-website hooks
 *
 * Provides mock data for useAuth, useConfig, etc.
 * Note: For ESM mode, use jest.unstable_mockModule() in test files
 * with these exported values. See Logon.test.tsx for the pattern.
 */

import type { CwcLogin } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';

// ============================================================================
// Config Mocks
// ============================================================================

/**
 * Default mock config for unit tests
 */
export const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

/**
 * Create a mock config with overrides
 */
export function createMockConfig(overrides?: Partial<CwcWebsiteConfig>): CwcWebsiteConfig {
  return {
    ...mockConfig,
    ...overrides,
  };
}

// ============================================================================
// Login/Auth Mocks
// ============================================================================

/**
 * Default mock login for guest user
 */
export const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

/**
 * Create a mock authenticated login with overrides
 */
export function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

packages/cwc-website/src/__tests__/mocks/index.ts

3 versions

Version 1

/**
 * Barrel export for test mocks
 */

export {
  mockNavigate,
  mockUseFetcher,
  setMockLocationState,
  clearMockLocationState,
  setMockParams,
  clearMockParams,
  setMockOutletContext,
  clearMockOutletContext,
  createMockFetcher,
  resetRouterMocks,
} from './router.mock';

export {
  mockGuestLogin,
  createMockAuthenticatedLogin,
  mockSetLoginFromJwt,
  mockLogoff,
  setMockAuth,
  resetMockAuth,
  mockConfig,
  createMockConfig,
} from './hooks.mock';

Version 2

/**
 * Barrel export for test mocks
 *
 * Usage in test files with ESM mocking:
 *
 * ```typescript
 * import { mockConfig, mockGuestLogin, createMockCodingSession } from '@/__tests__/mocks';
 *
 * jest.unstable_mockModule('@/hooks', () => ({
 *   useConfig: () => mockConfig,
 *   useAuth: () => ({ login: mockGuestLogin, ... }),
 * }));
 * ```
 */

// Config and auth mocks
export { mockConfig, createMockConfig, mockGuestLogin, createMockAuthenticatedLogin } from './hooks.mock';

// Router helpers
export { createMockFetcher, createMockLocation, MockLink } from './router.mock';

// Entity factories
export { createMockCodingSession, createMockSessionData, createMockUser } from './entities.mock';

Version 3 (latest)

/**
 * Barrel export for test mocks
 *
 * Usage in test files with ESM mocking:
 *
 * ```typescript
 * import { mockConfig, mockGuestLogin, createMockCodingSession } from '@/__tests__/mocks';
 *
 * jest.unstable_mockModule('@/hooks', () => ({
 *   useConfig: () => mockConfig,
 *   useAuth: () => ({ login: mockGuestLogin, ... }),
 * }));
 * ```
 */

// Config and auth mocks
export { mockConfig, createMockConfig, mockGuestLogin, createMockAuthenticatedLogin } from './hooks.mock';

// Router helpers
export { createMockFetcher, createMockLocation, MockLink } from './router.mock';

// Entity factories
export {
  createMockCodingSession,
  createMockProject,
  createMockSessionData,
  createMockUser,
} from './entities.mock';

packages/cwc-website/src/__tests__/mocks/router.mock.tsx

4 versions

Version 1

/**
 * React Router mocks for testing
 *
 * Provides mock implementations of React Router hooks and components.
 */

import type { ReactNode } from 'react';

// Mock navigation functions
export const mockNavigate = jest.fn();
export const mockUseFetcher = jest.fn();

// Mock useLocation state
let mockLocationState: Record<string, unknown> = {};

export function setMockLocationState(state: Record<string, unknown>): void {
  mockLocationState = state;
}

export function clearMockLocationState(): void {
  mockLocationState = {};
}

// Mock useParams values
let mockParams: Record<string, string> = {};

export function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

export function clearMockParams(): void {
  mockParams = {};
}

// Mock outlet context
let mockOutletContext: Record<string, unknown> = {};

export function setMockOutletContext(context: Record<string, unknown>): void {
  mockOutletContext = context;
}

export function clearMockOutletContext(): void {
  mockOutletContext = {};
}

// Create mock fetcher
export function createMockFetcher(overrides?: {
  state?: 'idle' | 'submitting' | 'loading';
  data?: unknown;
}) {
  return {
    state: overrides?.state ?? 'idle',
    data: overrides?.data ?? undefined,
    submit: jest.fn(),
    load: jest.fn(),
    Form: ({ children }: { children: ReactNode }) => <form>{children}</form>,
    formData: undefined,
    formAction: undefined,
    formEncType: undefined,
    formMethod: undefined,
  };
}

// Jest mock implementations
jest.mock('react-router', () => ({
  ...jest.requireActual('react-router'),
  useNavigate: () => mockNavigate,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: mockLocationState,
    key: 'default',
  }),
  useParams: () => mockParams,
  useOutletContext: () => mockOutletContext,
  useFetcher: () => mockUseFetcher(),
  Link: ({ to, children, ...props }: { to: string; children: ReactNode }) => (
    <a href={to} {...props}>
      {children}
    </a>
  ),
}));

// Reset all router mocks
export function resetRouterMocks(): void {
  mockNavigate.mockReset();
  mockUseFetcher.mockReset();
  clearMockLocationState();
  clearMockParams();
  clearMockOutletContext();
}

Version 2

/**
 * React Router mocks for testing
 *
 * Provides mock implementations of React Router hooks and components.
 */

import { jest } from '@jest/globals';
import type { ReactNode } from 'react';
import type { CwcWebsiteConfig } from '@/config';

// Default mock config for tests
const defaultMockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock navigation functions
export const mockNavigate = jest.fn();
export const mockUseFetcher = jest.fn();

// Mock useLocation state
let mockLocationState: Record<string, unknown> = {};

export function setMockLocationState(state: Record<string, unknown>): void {
  mockLocationState = state;
}

export function clearMockLocationState(): void {
  mockLocationState = {};
}

// Mock useParams values
let mockParams: Record<string, string> = {};

export function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

export function clearMockParams(): void {
  mockParams = {};
}

// Mock outlet context (includes config by default)
let mockOutletContext: Record<string, unknown> = { config: defaultMockConfig };

export function setMockOutletContext(context: Record<string, unknown>): void {
  mockOutletContext = context;
}

export function clearMockOutletContext(): void {
  mockOutletContext = { config: defaultMockConfig };
}

// Create mock fetcher
export function createMockFetcher(overrides?: {
  state?: 'idle' | 'submitting' | 'loading';
  data?: unknown;
}) {
  return {
    state: overrides?.state ?? 'idle',
    data: overrides?.data ?? undefined,
    submit: jest.fn(),
    load: jest.fn(),
    Form: ({ children }: { children: ReactNode }) => <form>{children}</form>,
    formData: undefined,
    formAction: undefined,
    formEncType: undefined,
    formMethod: undefined,
  };
}

// Jest mock implementations
jest.mock('react-router', () => ({
  ...jest.requireActual('react-router'),
  useNavigate: () => mockNavigate,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: mockLocationState,
    key: 'default',
  }),
  useParams: () => mockParams,
  useOutletContext: () => mockOutletContext,
  useFetcher: () => mockUseFetcher(),
  Link: ({ to, children, ...props }: { to: string; children: ReactNode }) => (
    <a href={to} {...props}>
      {children}
    </a>
  ),
}));

// Reset all router mocks
export function resetRouterMocks(): void {
  mockNavigate.mockReset();
  mockUseFetcher.mockReset();
  clearMockLocationState();
  clearMockParams();
  clearMockOutletContext();
}

Version 3

/**
 * React Router mocks for testing
 *
 * Provides mock implementations of React Router hooks and components.
 */

import { jest } from '@jest/globals';
import type { ReactNode } from 'react';
import type { CwcWebsiteConfig } from '@/config';

// Default mock config for tests
const defaultMockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock navigation functions
export const mockNavigate = jest.fn();
export const mockUseFetcher = jest.fn();

// Mock useLocation state
let mockLocationState: Record<string, unknown> = {};

export function setMockLocationState(state: Record<string, unknown>): void {
  mockLocationState = state;
}

export function clearMockLocationState(): void {
  mockLocationState = {};
}

// Mock useParams values
let mockParams: Record<string, string> = {};

export function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

export function clearMockParams(): void {
  mockParams = {};
}

// Mock outlet context (includes config by default)
let mockOutletContext: Record<string, unknown> = { config: defaultMockConfig };

export function setMockOutletContext(context: Record<string, unknown>): void {
  mockOutletContext = context;
}

export function clearMockOutletContext(): void {
  mockOutletContext = { config: defaultMockConfig };
}

// Create mock fetcher
export function createMockFetcher(overrides?: {
  state?: 'idle' | 'submitting' | 'loading';
  data?: unknown;
}) {
  return {
    state: overrides?.state ?? 'idle',
    data: overrides?.data ?? undefined,
    submit: jest.fn(),
    load: jest.fn(),
    Form: ({ children }: { children: ReactNode }) => <form>{children}</form>,
    formData: undefined,
    formAction: undefined,
    formEncType: undefined,
    formMethod: undefined,
  };
}

// Jest mock implementations
// Note: This mock is for reference only. In ESM mode, use jest.unstable_mockModule
// directly in test files with dynamic imports. See Logon.test.tsx for the pattern.
jest.mock('react-router', () => ({
  ...(jest.requireActual('react-router') as object),
  useNavigate: () => mockNavigate,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: mockLocationState,
    key: 'default',
  }),
  useParams: () => mockParams,
  useOutletContext: () => mockOutletContext,
  useFetcher: () => mockUseFetcher(),
  Link: ({ to, children, ...props }: { to: string; children: ReactNode }) => (
    <a href={to} {...props}>
      {children}
    </a>
  ),
}));

// Reset all router mocks
export function resetRouterMocks(): void {
  mockNavigate.mockReset();
  mockUseFetcher.mockReset();
  clearMockLocationState();
  clearMockParams();
  clearMockOutletContext();
}

Version 4 (latest)

/**
 * React Router mock helpers for testing
 *
 * Provides helper functions for creating React Router mocks.
 * Note: For ESM mode, use jest.unstable_mockModule() in test files
 * with these helpers. See Logon.test.tsx for the pattern.
 */

import type { ReactNode } from 'react';

/**
 * Create a mock fetcher for useFetcher
 */
export function createMockFetcher(overrides?: {
  state?: 'idle' | 'submitting' | 'loading';
  data?: unknown;
  submit?: () => void;
}) {
  return {
    state: overrides?.state ?? 'idle',
    data: overrides?.data ?? undefined,
    submit: overrides?.submit ?? (() => {}),
    load: () => {},
    Form: ({ children }: { children: ReactNode }) => <form>{children}</form>,
    formData: undefined,
    formAction: undefined,
    formEncType: undefined,
    formMethod: undefined,
  };
}

/**
 * Create a mock location object
 */
export function createMockLocation(overrides?: {
  pathname?: string;
  search?: string;
  hash?: string;
  state?: Record<string, unknown>;
  key?: string;
}) {
  return {
    pathname: overrides?.pathname ?? '/',
    search: overrides?.search ?? '',
    hash: overrides?.hash ?? '',
    state: overrides?.state ?? {},
    key: overrides?.key ?? 'default',
  };
}

/**
 * Mock Link component for testing
 */
export function MockLink({
  to,
  children,
  ...props
}: {
  to: string;
  children: ReactNode;
  [key: string]: unknown;
}) {
  return (
    <a href={to} {...props}>
      {children}
    </a>
  );
}

packages/cwc-website/src/__tests__/mocks/styleMock.ts

/**
 * Mock for CSS/SCSS imports in Jest tests
 *
 * Jest doesn't process CSS files, so we mock them as empty objects.
 */
export default {};

packages/cwc-website/src/__tests__/setup.ts

3 versions

Version 1

/**
 * Jest setup file for cwc-website
 *
 * Configures:
 * - @testing-library/jest-dom matchers
 * - Global mocks for browser APIs
 * - React Router mocks
 */

import '@testing-library/jest-dom';

// Mock window.matchMedia (used by theme detection)
Object.defineProperty(window, 'matchMedia', {
  writable: true,
  value: jest.fn().mockImplementation((query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addListener: jest.fn(),
    removeListener: jest.fn(),
    addEventListener: jest.fn(),
    removeEventListener: jest.fn(),
    dispatchEvent: jest.fn(),
  })),
});

// Mock localStorage
const localStorageMock = (() => {
  let store: Record<string, string> = {};
  return {
    getItem: jest.fn((key: string) => store[key] ?? null),
    setItem: jest.fn((key: string, value: string) => {
      store[key] = value;
    }),
    removeItem: jest.fn((key: string) => {
      delete store[key];
    }),
    clear: jest.fn(() => {
      store = {};
    }),
    get length() {
      return Object.keys(store).length;
    },
    key: jest.fn((index: number) => Object.keys(store)[index] ?? null),
  };
})();

Object.defineProperty(window, 'localStorage', {
  value: localStorageMock,
});

// Mock crypto.randomUUID (used for device ID generation)
Object.defineProperty(window, 'crypto', {
  value: {
    randomUUID: jest.fn(() => 'test-uuid-1234-5678-9012'),
    getRandomValues: jest.fn((arr: Uint8Array) => {
      for (let i = 0; i < arr.length; i++) {
        arr[i] = Math.floor(Math.random() * 256);
      }
      return arr;
    }),
  },
});

// Mock scrollIntoView (used in editor)
Element.prototype.scrollIntoView = jest.fn();

// Clear mocks between tests
beforeEach(() => {
  jest.clearAllMocks();
  localStorageMock.clear();
});

Version 2

/**
 * Jest setup file for cwc-website
 *
 * Configures:
 * - @testing-library/jest-dom matchers
 * - Global mocks for browser APIs
 *
 * Note: For ESM module mocking, use jest.unstable_mockModule() in test files
 * with dynamic imports. See Logon.test.tsx for the pattern.
 */

import { jest, beforeEach } from '@jest/globals';
import { TextEncoder, TextDecoder } from 'util';
import '@testing-library/jest-dom';

// Polyfill TextEncoder/TextDecoder for jsdom (required by React Router)
Object.defineProperty(globalThis, 'TextEncoder', { value: TextEncoder });
Object.defineProperty(globalThis, 'TextDecoder', { value: TextDecoder });

// Mock window.matchMedia (used by theme detection)
Object.defineProperty(window, 'matchMedia', {
  writable: true,
  value: jest.fn().mockImplementation((query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addListener: jest.fn(),
    removeListener: jest.fn(),
    addEventListener: jest.fn(),
    removeEventListener: jest.fn(),
    dispatchEvent: jest.fn(),
  })),
});

// Mock localStorage
const localStorageMock = (() => {
  let store: Record<string, string> = {};
  return {
    getItem: jest.fn((key: string) => store[key] ?? null),
    setItem: jest.fn((key: string, value: string) => {
      store[key] = value;
    }),
    removeItem: jest.fn((key: string) => {
      delete store[key];
    }),
    clear: jest.fn(() => {
      store = {};
    }),
    get length() {
      return Object.keys(store).length;
    },
    key: jest.fn((index: number) => Object.keys(store)[index] ?? null),
  };
})();

Object.defineProperty(window, 'localStorage', {
  value: localStorageMock,
});

// Mock crypto.randomUUID (used for device ID generation)
Object.defineProperty(window, 'crypto', {
  value: {
    randomUUID: jest.fn(() => 'test-uuid-1234-5678-9012'),
    getRandomValues: jest.fn((arr: Uint8Array) => {
      for (let i = 0; i < arr.length; i++) {
        arr[i] = Math.floor(Math.random() * 256);
      }
      return arr;
    }),
  },
});

// Mock scrollIntoView (used in editor)
Element.prototype.scrollIntoView = jest.fn();

// Clear mocks between tests
beforeEach(() => {
  jest.clearAllMocks();
  localStorageMock.clear();
});

Version 3 (latest)

/**
 * Jest setup file for cwc-website
 *
 * Configures:
 * - @testing-library/jest-dom matchers
 * - Global mocks for browser APIs
 *
 * Note: For ESM module mocking, use jest.unstable_mockModule() in test files
 * with dynamic imports. See Logon.test.tsx for the pattern.
 */

import { jest, beforeEach } from '@jest/globals';
import { TextEncoder, TextDecoder } from 'util';
// Use jest-globals entry point for Jest 30 + @jest/globals type compatibility
import '@testing-library/jest-dom/jest-globals';

// Polyfill TextEncoder/TextDecoder for jsdom (required by React Router)
Object.defineProperty(globalThis, 'TextEncoder', { value: TextEncoder });
Object.defineProperty(globalThis, 'TextDecoder', { value: TextDecoder });

// Mock window.matchMedia (used by theme detection)
Object.defineProperty(window, 'matchMedia', {
  writable: true,
  value: jest.fn<(query: string) => MediaQueryList>().mockImplementation((query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addListener: jest.fn(),
    removeListener: jest.fn(),
    addEventListener: jest.fn(),
    removeEventListener: jest.fn(),
    dispatchEvent: jest.fn(),
  }) as MediaQueryList),
});

// Mock localStorage
const localStorageMock = (() => {
  let store: Record<string, string> = {};
  return {
    getItem: jest.fn((key: string) => store[key] ?? null),
    setItem: jest.fn((key: string, value: string) => {
      store[key] = value;
    }),
    removeItem: jest.fn((key: string) => {
      delete store[key];
    }),
    clear: jest.fn(() => {
      store = {};
    }),
    get length() {
      return Object.keys(store).length;
    },
    key: jest.fn((index: number) => Object.keys(store)[index] ?? null),
  };
})();

Object.defineProperty(window, 'localStorage', {
  value: localStorageMock,
});

// Mock crypto.randomUUID (used for device ID generation)
Object.defineProperty(window, 'crypto', {
  value: {
    randomUUID: jest.fn(() => 'test-uuid-1234-5678-9012'),
    getRandomValues: jest.fn((arr: Uint8Array) => {
      for (let i = 0; i < arr.length; i++) {
        arr[i] = Math.floor(Math.random() * 256);
      }
      return arr;
    }),
  },
});

// Mock scrollIntoView (used in editor)
Element.prototype.scrollIntoView = jest.fn();

// Clear mocks between tests
beforeEach(() => {
  jest.clearAllMocks();
  localStorageMock.clear();
});

packages/cwc-website/src/__tests__/testing-library.d.ts

/**
 * Type declarations for @testing-library/jest-dom matchers
 *
 * These extend Jest's expect() with DOM-specific matchers.
 * Required because Jest 30 + ESM + @jest/globals imports
 * don't automatically pick up jest-dom's type extensions.
 */

import type { TestingLibraryMatchers } from '@testing-library/jest-dom/matchers';

declare module '@jest/expect' {
  interface Matchers<R = void>
    extends TestingLibraryMatchers<typeof expect.stringContaining, R> {}
}

packages/cwc-website/src/__tests__/views/client/CodingSessionEditor/CodingSessionEditor.test.tsx

4 versions

Version 1

/**
 * Unit tests for CodingSessionEditor page
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { render, screen, waitFor, fireEvent } from '@testing-library/react';
import type { ReactNode } from 'react';
import type { CwcLogin } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';
import type { EditorDataState } from '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData';

// Default mock config
const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock login state
const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;
let mockParams: Record<string, string> = {};
let mockEditorDataState: EditorDataState = { status: 'loading' };

// Mock functions
const mockNavigate = jest.fn();

// Set up ESM mocks before importing component
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  useParams: () => mockParams,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: {},
    key: 'default',
  }),
}));

jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
}));

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData',
  () => ({
    useCodingSessionEditorData: () => mockEditorDataState,
  })
);

jest.unstable_mockModule('@/components/ui/scroll-area', () => ({
  ScrollArea: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
}));

// Mock the editor components
jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/EditorToolbar',
  () => ({
    EditorToolbar: ({
      projectId,
      sessionId,
      isDirty,
      isSaving,
      onSave,
      onUndo,
      onDelete,
    }: {
      projectId: string;
      sessionId: string;
      isDirty: boolean;
      isSaving: boolean;
      onSave: () => void;
      onUndo: () => void;
      onDelete: () => void;
    }) => (
      <div data-testid="editor-toolbar">
        <span>Project: {projectId}</span>
        <span>Session: {sessionId}</span>
        <button onClick={onSave} disabled={isSaving}>
          Save
        </button>
        <button onClick={onUndo}>Undo</button>
        <button onClick={onDelete}>Delete</button>
      </div>
    ),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SessionMetadataEditor',
  () => ({
    SessionMetadataEditor: () => <div data-testid="session-metadata-editor">Metadata Editor</div>,
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/MessageEditor',
  () => ({
    MessageEditor: () => <div data-testid="message-editor">Message Editor</div>,
    buildHighlightMap: () => new Map(),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SensitiveDataSearch',
  () => ({
    SensitiveDataSearch: () => <div data-testid="sensitive-data-search">Sensitive Data Search</div>,
  })
);

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSessionEditor', () => ({
  useSessionEditor: () => ({
    description: 'Test session',
    published: true,
    sessionData: { messages: [] },
    isDirty: false,
    isMetadataDirty: false,
    isContentDirty: false,
    canUndo: false,
    setDescription: jest.fn(),
    setPublished: jest.fn(),
    deleteMessage: jest.fn(),
    updateContentBlock: jest.fn(),
    deleteContentBlock: jest.fn(),
    undo: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSensitiveSearch', () => ({
  useSensitiveSearch: () => ({
    matches: [],
    activePatterns: new Set(),
    customPatterns: [],
    builtInPatterns: [],
    togglePattern: jest.fn(),
    addCustomPattern: jest.fn(),
    removeCustomPattern: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientUpdateCodingSession: jest.fn(),
  clientUpdateSessionContent: jest.fn(),
  clientDeleteCodingSession: jest.fn(),
}));

// Dynamic import of component after mocks are set up
const { default: CodingSessionEditor } = await import(
  '@/views/client/CodingSessionEditor/CodingSessionEditor'
);

// Helper functions
function resetMocks(): void {
  mockNavigate.mockReset();
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockParams = {};
  mockEditorDataState = { status: 'loading' };
}

function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

function setMockEditorState(state: EditorDataState): void {
  mockEditorDataState = state;
}

describe('CodingSessionEditor', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('loading state', () => {
    it('shows loading spinner when data is loading', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'loading' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Loading session editor...')).toBeInTheDocument();
    });
  });

  describe('error state', () => {
    it('shows error message when data fails to load', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Error Loading Session')).toBeInTheDocument();
      expect(screen.getByText('Session not found')).toBeInTheDocument();
    });

    it('navigates back when Go Back button is clicked', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      expect(mockNavigate).toHaveBeenCalledWith('/project/test-project');
    });

    it('navigates to home if projectId is not available', () => {
      setMockParams({ sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Project ID required' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      expect(mockNavigate).toHaveBeenCalledWith('/');
    });
  });

  describe('unauthorized state', () => {
    it('shows unauthorized message when user lacks permission', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'You do not have permission to edit this session',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Access Denied')).toBeInTheDocument();
      expect(
        screen.getByText('You do not have permission to edit this session')
      ).toBeInTheDocument();
    });

    it('shows lock icon in unauthorized state', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'Not authorized',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('🔒')).toBeInTheDocument();
    });
  });

  describe('ready state', () => {
    beforeEach(() => {
      setMockParams({ projectId: 'coding-with-claude', sessionId: 'session-001' });
      setMockAuth(createMockAuthenticatedLogin(), true);
      setMockEditorState({
        status: 'ready',
        data: {
          projectId: 'coding-with-claude',
          session: {
            codingSessionPkId: 1,
            sessionId: 'session-001',
            storageKey: 'session-001.json.gz',
            userPkId: 1,
            projectPkId: 1,
            projectId: 'coding-with-claude',
            title: 'Test Session',
            description: 'A test session',
            published: true,
            createdAt: '2024-01-01T00:00:00Z',
            updatedAt: '2024-01-01T00:00:00Z',
          },
          sessionData: {
            messages: [],
            summary: 'Test summary',
          },
          projectOwnerUsername: 'testuser',
        },
      });
    });

    it('renders the editor toolbar', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('editor-toolbar')).toBeInTheDocument();
    });

    it('renders the session metadata editor', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('session-metadata-editor')).toBeInTheDocument();
    });

    it('renders the sensitive data search component', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('sensitive-data-search')).toBeInTheDocument();
    });

    it('shows message count', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByText('Messages (0)')).toBeInTheDocument();
    });
  });
});

Version 2

/**
 * Unit tests for CodingSessionEditor page
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { render, screen, fireEvent } from '@testing-library/react';
import type { ReactNode } from 'react';
import type { CwcLogin, CwcCodingSession, CwcSessionData } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';
import type { EditorDataState } from '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData';

// Helper to create mock CodingSession
function createMockCodingSession(overrides?: Partial<CwcCodingSession>): CwcCodingSession {
  return {
    codingSessionPkId: 1,
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    userPkId: 1,
    projectPkId: 1,
    description: 'Test session',
    published: true,
    sessionId: 'session-001',
    storageKey: 'session-001.json.gz',
    startTimestamp: '2024-01-01T00:00:00Z',
    endTimestamp: '2024-01-01T01:00:00Z',
    gitBranch: 'main',
    model: 'claude-3-opus',
    messageCount: 10,
    filesModifiedCount: 5,
    ...overrides,
  };
}

// Helper to create mock SessionData
function createMockSessionData(overrides?: Partial<CwcSessionData>): CwcSessionData {
  return {
    formatVersion: '1.0.0',
    sessionId: 'session-001',
    projectSessionFolder: 'coding-with-claude',
    startTimestamp: '2024-01-01T00:00:00.000Z',
    endTimestamp: '2024-01-01T01:00:00.000Z',
    model: 'claude-3-opus',
    gitBranch: 'main',
    summary: 'Test summary',
    cwd: '/path/to/project',
    claudeCodeVersion: '2.0.42',
    messages: [],
    files: [],
    stats: {
      totalMessages: 10,
      userMessages: 5,
      assistantMessages: 5,
      filesModified: 3,
      totalTokens: { input: 1000, output: 2000, cacheRead: 0, cacheCreation: 0 },
    },
    ...overrides,
  };
}

// Default mock config
const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock login state
const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;
let mockParams: Record<string, string> = {};
let mockEditorDataState: EditorDataState = { status: 'loading' };

// Mock functions
const mockNavigate = jest.fn();

// Set up ESM mocks before importing component
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  useParams: () => mockParams,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: {},
    key: 'default',
  }),
}));

jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
}));

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData',
  () => ({
    useCodingSessionEditorData: () => mockEditorDataState,
  })
);

jest.unstable_mockModule('@/components/ui/scroll-area', () => ({
  ScrollArea: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
}));

// Mock the editor components
jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/EditorToolbar',
  () => ({
    EditorToolbar: ({
      projectId,
      sessionId,
      isDirty,
      isSaving,
      onSave,
      onUndo,
      onDelete,
    }: {
      projectId: string;
      sessionId: string;
      isDirty: boolean;
      isSaving: boolean;
      onSave: () => void;
      onUndo: () => void;
      onDelete: () => void;
    }) => (
      <div data-testid="editor-toolbar">
        <span>Project: {projectId}</span>
        <span>Session: {sessionId}</span>
        <button onClick={onSave} disabled={isSaving}>
          Save
        </button>
        <button onClick={onUndo}>Undo</button>
        <button onClick={onDelete}>Delete</button>
      </div>
    ),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SessionMetadataEditor',
  () => ({
    SessionMetadataEditor: () => <div data-testid="session-metadata-editor">Metadata Editor</div>,
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/MessageEditor',
  () => ({
    MessageEditor: () => <div data-testid="message-editor">Message Editor</div>,
    buildHighlightMap: () => new Map(),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SensitiveDataSearch',
  () => ({
    SensitiveDataSearch: () => <div data-testid="sensitive-data-search">Sensitive Data Search</div>,
  })
);

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSessionEditor', () => ({
  useSessionEditor: () => ({
    description: 'Test session',
    published: true,
    sessionData: { messages: [] },
    isDirty: false,
    isMetadataDirty: false,
    isContentDirty: false,
    canUndo: false,
    setDescription: jest.fn(),
    setPublished: jest.fn(),
    deleteMessage: jest.fn(),
    updateContentBlock: jest.fn(),
    deleteContentBlock: jest.fn(),
    undo: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSensitiveSearch', () => ({
  useSensitiveSearch: () => ({
    matches: [],
    activePatterns: new Set(),
    customPatterns: [],
    builtInPatterns: [],
    togglePattern: jest.fn(),
    addCustomPattern: jest.fn(),
    removeCustomPattern: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientUpdateCodingSession: jest.fn(),
  clientUpdateSessionContent: jest.fn(),
  clientDeleteCodingSession: jest.fn(),
}));

// Dynamic import of component after mocks are set up
const { default: CodingSessionEditor } = await import(
  '@/views/client/CodingSessionEditor/CodingSessionEditor'
);

// Helper functions
function resetMocks(): void {
  mockNavigate.mockReset();
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockParams = {};
  mockEditorDataState = { status: 'loading' };
}

function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

function setMockEditorState(state: EditorDataState): void {
  mockEditorDataState = state;
}

describe('CodingSessionEditor', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('loading state', () => {
    it('shows loading spinner when data is loading', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'loading' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Loading session editor...')).toBeInTheDocument();
    });
  });

  describe('error state', () => {
    it('shows error message when data fails to load', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Error Loading Session')).toBeInTheDocument();
      expect(screen.getByText('Session not found')).toBeInTheDocument();
    });

    it('navigates back when Go Back button is clicked', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      expect(mockNavigate).toHaveBeenCalledWith('/project/test-project');
    });

    it('navigates to home if projectId is not available', () => {
      setMockParams({ sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Project ID required' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      expect(mockNavigate).toHaveBeenCalledWith('/');
    });
  });

  describe('unauthorized state', () => {
    it('shows unauthorized message when user lacks permission', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'You do not have permission to edit this session',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Access Denied')).toBeInTheDocument();
      expect(
        screen.getByText('You do not have permission to edit this session')
      ).toBeInTheDocument();
    });

    it('shows lock icon in unauthorized state', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'Not authorized',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('🔒')).toBeInTheDocument();
    });
  });

  describe('ready state', () => {
    beforeEach(() => {
      setMockParams({ projectId: 'coding-with-claude', sessionId: 'session-001' });
      setMockAuth(createMockAuthenticatedLogin(), true);
      setMockEditorState({
        status: 'ready',
        data: {
          projectId: 'coding-with-claude',
          session: createMockCodingSession(),
          sessionData: createMockSessionData(),
          projectOwnerUsername: 'testuser',
        },
      });
    });

    it('renders the editor toolbar', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('editor-toolbar')).toBeInTheDocument();
    });

    it('renders the session metadata editor', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('session-metadata-editor')).toBeInTheDocument();
    });

    it('renders the sensitive data search component', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('sensitive-data-search')).toBeInTheDocument();
    });

    it('shows message count', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByText('Messages (0)')).toBeInTheDocument();
    });
  });
});

Version 3

/**
 * Unit tests for CodingSessionEditor page
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { render, screen, fireEvent } from '@testing-library/react';
import type { ReactNode } from 'react';
import type { CwcLogin } from 'cwc-types';
import type { EditorDataState } from '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData';
import {
  mockConfig,
  mockGuestLogin,
  createMockAuthenticatedLogin,
  createMockCodingSession,
  createMockSessionData,
} from '@/__tests__/mocks';

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;
let mockParams: Record<string, string> = {};
let mockEditorDataState: EditorDataState = { status: 'loading' };

// Mock functions
const mockNavigate = jest.fn();

// Set up ESM mocks before importing component
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  useParams: () => mockParams,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: {},
    key: 'default',
  }),
}));

jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
}));

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData',
  () => ({
    useCodingSessionEditorData: () => mockEditorDataState,
  })
);

jest.unstable_mockModule('@/components/ui/scroll-area', () => ({
  ScrollArea: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
}));

// Mock the editor components
jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/EditorToolbar',
  () => ({
    EditorToolbar: ({
      projectId,
      sessionId,
      isDirty,
      isSaving,
      onSave,
      onUndo,
      onDelete,
    }: {
      projectId: string;
      sessionId: string;
      isDirty: boolean;
      isSaving: boolean;
      onSave: () => void;
      onUndo: () => void;
      onDelete: () => void;
    }) => (
      <div data-testid="editor-toolbar">
        <span>Project: {projectId}</span>
        <span>Session: {sessionId}</span>
        <button onClick={onSave} disabled={isSaving}>
          Save
        </button>
        <button onClick={onUndo}>Undo</button>
        <button onClick={onDelete}>Delete</button>
      </div>
    ),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SessionMetadataEditor',
  () => ({
    SessionMetadataEditor: () => <div data-testid="session-metadata-editor">Metadata Editor</div>,
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/MessageEditor',
  () => ({
    MessageEditor: () => <div data-testid="message-editor">Message Editor</div>,
    buildHighlightMap: () => new Map(),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SensitiveDataSearch',
  () => ({
    SensitiveDataSearch: () => <div data-testid="sensitive-data-search">Sensitive Data Search</div>,
  })
);

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSessionEditor', () => ({
  useSessionEditor: () => ({
    description: 'Test session',
    published: true,
    sessionData: { messages: [] },
    isDirty: false,
    isMetadataDirty: false,
    isContentDirty: false,
    canUndo: false,
    setDescription: jest.fn(),
    setPublished: jest.fn(),
    deleteMessage: jest.fn(),
    updateContentBlock: jest.fn(),
    deleteContentBlock: jest.fn(),
    undo: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSensitiveSearch', () => ({
  useSensitiveSearch: () => ({
    matches: [],
    activePatterns: new Set(),
    customPatterns: [],
    builtInPatterns: [],
    togglePattern: jest.fn(),
    addCustomPattern: jest.fn(),
    removeCustomPattern: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientUpdateCodingSession: jest.fn(),
  clientUpdateSessionContent: jest.fn(),
  clientDeleteCodingSession: jest.fn(),
}));

// Dynamic import of component after mocks are set up
const { default: CodingSessionEditor } = await import(
  '@/views/client/CodingSessionEditor/CodingSessionEditor'
);

// Helper functions
function resetMocks(): void {
  mockNavigate.mockReset();
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockParams = {};
  mockEditorDataState = { status: 'loading' };
}

function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

function setMockEditorState(state: EditorDataState): void {
  mockEditorDataState = state;
}

describe('CodingSessionEditor', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('loading state', () => {
    it('shows loading spinner when data is loading', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'loading' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Loading session editor...')).toBeInTheDocument();
    });
  });

  describe('error state', () => {
    it('shows error message when data fails to load', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Error Loading Session')).toBeInTheDocument();
      expect(screen.getByText('Session not found')).toBeInTheDocument();
    });

    it('navigates back when Go Back button is clicked', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      expect(mockNavigate).toHaveBeenCalledWith('/project/test-project');
    });

    it('navigates to home if projectId is not available', () => {
      setMockParams({ sessionId: 'test-session' });
      setMockEditorState({ status: 'error', error: 'Project ID required' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      expect(mockNavigate).toHaveBeenCalledWith('/');
    });
  });

  describe('unauthorized state', () => {
    it('shows unauthorized message when user lacks permission', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'You do not have permission to edit this session',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Access Denied')).toBeInTheDocument();
      expect(
        screen.getByText('You do not have permission to edit this session')
      ).toBeInTheDocument();
    });

    it('shows lock icon in unauthorized state', () => {
      setMockParams({ projectId: 'test-project', sessionId: 'test-session' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'Not authorized',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('🔒')).toBeInTheDocument();
    });
  });

  describe('ready state', () => {
    beforeEach(() => {
      setMockParams({ projectId: 'coding-with-claude', sessionId: 'session-001' });
      setMockAuth(createMockAuthenticatedLogin(), true);
      setMockEditorState({
        status: 'ready',
        data: {
          projectId: 'coding-with-claude',
          session: createMockCodingSession(),
          sessionData: createMockSessionData(),
          projectOwnerUsername: 'testuser',
        },
      });
    });

    it('renders the editor toolbar', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('editor-toolbar')).toBeInTheDocument();
    });

    it('renders the session metadata editor', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('session-metadata-editor')).toBeInTheDocument();
    });

    it('renders the sensitive data search component', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('sensitive-data-search')).toBeInTheDocument();
    });

    it('shows message count', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByText('Messages (0)')).toBeInTheDocument();
    });
  });
});

Version 4 (latest)

/**
 * Unit tests for CodingSessionEditor page
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { render, screen, fireEvent } from '@testing-library/react';
import type { ReactNode } from 'react';
import type { CwcLogin } from 'cwc-types';
import type { EditorDataState } from '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData';
import {
  mockConfig,
  mockGuestLogin,
  createMockAuthenticatedLogin,
  createMockCodingSession,
  createMockSessionData,
} from '@/__tests__/mocks';

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;
let mockParams: Record<string, string> = {};
let mockEditorDataState: EditorDataState = { status: 'loading' };

// Mock functions
const mockNavigate = jest.fn();

// Set up ESM mocks before importing component
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  useParams: () => mockParams,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: {},
    key: 'default',
  }),
}));

jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
}));

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData',
  () => ({
    useCodingSessionEditorData: () => mockEditorDataState,
  })
);

jest.unstable_mockModule('@/components/ui/scroll-area', () => ({
  ScrollArea: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
}));

// Mock the editor components
jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/EditorToolbar',
  () => ({
    EditorToolbar: ({
      codingSessionPkId,
      isDirty,
      isSaving,
      onSave,
      onUndo,
      onDelete,
    }: {
      codingSessionPkId: number;
      isDirty: boolean;
      isSaving: boolean;
      onSave: () => void;
      onUndo: () => void;
      onDelete: () => void;
    }) => (
      <div data-testid="editor-toolbar">
        <span>Session PkId: {codingSessionPkId}</span>
        <button onClick={onSave} disabled={isSaving}>
          Save
        </button>
        <button onClick={onUndo}>Undo</button>
        <button onClick={onDelete}>Delete</button>
      </div>
    ),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SessionMetadataEditor',
  () => ({
    SessionMetadataEditor: () => <div data-testid="session-metadata-editor">Metadata Editor</div>,
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/MessageEditor',
  () => ({
    MessageEditor: () => <div data-testid="message-editor">Message Editor</div>,
    buildHighlightMap: () => new Map(),
  })
);

jest.unstable_mockModule(
  '@/views/client/CodingSessionEditor/components/SensitiveDataSearch',
  () => ({
    SensitiveDataSearch: () => <div data-testid="sensitive-data-search">Sensitive Data Search</div>,
  })
);

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSessionEditor', () => ({
  useSessionEditor: () => ({
    description: 'Test session',
    published: true,
    sessionData: { messages: [] },
    isDirty: false,
    isMetadataDirty: false,
    isContentDirty: false,
    canUndo: false,
    setDescription: jest.fn(),
    setPublished: jest.fn(),
    deleteMessage: jest.fn(),
    updateContentBlock: jest.fn(),
    deleteContentBlock: jest.fn(),
    undo: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/views/client/CodingSessionEditor/hooks/useSensitiveSearch', () => ({
  useSensitiveSearch: () => ({
    matches: [],
    activePatterns: new Set(),
    customPatterns: [],
    builtInPatterns: [],
    togglePattern: jest.fn(),
    addCustomPattern: jest.fn(),
    removeCustomPattern: jest.fn(),
  }),
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientUpdateCodingSession: jest.fn(),
  clientUpdateSessionContent: jest.fn(),
  clientDeleteCodingSession: jest.fn(),
}));

// Dynamic import of component after mocks are set up
const { default: CodingSessionEditor } = await import(
  '@/views/client/CodingSessionEditor/CodingSessionEditor'
);

// Helper functions
function resetMocks(): void {
  mockNavigate.mockReset();
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockParams = {};
  mockEditorDataState = { status: 'loading' };
}

function setMockParams(params: Record<string, string>): void {
  mockParams = params;
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

function setMockEditorState(state: EditorDataState): void {
  mockEditorDataState = state;
}

describe('CodingSessionEditor', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('loading state', () => {
    it('shows loading spinner when data is loading', () => {
      setMockParams({ codingSessionPkId: '42' });
      setMockEditorState({ status: 'loading' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Loading session editor...')).toBeInTheDocument();
    });
  });

  describe('error state', () => {
    it('shows error message when data fails to load', () => {
      setMockParams({ codingSessionPkId: '42' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Error Loading Session')).toBeInTheDocument();
      expect(screen.getByText('Session not found')).toBeInTheDocument();
    });

    it('navigates to home when Go Back button is clicked', () => {
      setMockParams({ codingSessionPkId: '42' });
      setMockEditorState({ status: 'error', error: 'Session not found' });

      render(<CodingSessionEditor />);

      fireEvent.click(screen.getByText('Go Back'));

      // Now always navigates to home since projectId is not in URL params
      expect(mockNavigate).toHaveBeenCalledWith('/');
    });
  });

  describe('unauthorized state', () => {
    it('shows unauthorized message when user lacks permission', () => {
      setMockParams({ codingSessionPkId: '42' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'You do not have permission to edit this session',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('Access Denied')).toBeInTheDocument();
      expect(
        screen.getByText('You do not have permission to edit this session')
      ).toBeInTheDocument();
    });

    it('shows lock icon in unauthorized state', () => {
      setMockParams({ codingSessionPkId: '42' });
      setMockEditorState({
        status: 'unauthorized',
        message: 'Not authorized',
      });

      render(<CodingSessionEditor />);

      expect(screen.getByText('🔒')).toBeInTheDocument();
    });
  });

  describe('ready state', () => {
    beforeEach(() => {
      setMockParams({ codingSessionPkId: '1' });
      setMockAuth(createMockAuthenticatedLogin(), true);
      setMockEditorState({
        status: 'ready',
        data: {
          projectId: 'coding-with-claude',
          session: createMockCodingSession(),
          sessionData: createMockSessionData(),
          projectOwnerUsername: 'testuser',
        },
      });
    });

    it('renders the editor toolbar', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('editor-toolbar')).toBeInTheDocument();
    });

    it('renders the session metadata editor', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('session-metadata-editor')).toBeInTheDocument();
    });

    it('renders the sensitive data search component', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByTestId('sensitive-data-search')).toBeInTheDocument();
    });

    it('shows message count', () => {
      render(<CodingSessionEditor />);

      expect(screen.getByText('Messages (0)')).toBeInTheDocument();
    });
  });
});

packages/cwc-website/src/__tests__/views/client/CodingSessionEditor/useCodingSessionEditorData.test.ts

4 versions

Version 1

/**
 * Unit tests for useCodingSessionEditorData hook
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { renderHook, waitFor } from '@testing-library/react';
import type { CwcLogin } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';

// Default mock config
const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock login states
const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;

// Mock API functions
const mockClientGetCodingSession = jest.fn();
const mockClientGetSessionData = jest.fn();
const mockClientGetUser = jest.fn();

// Set up ESM mocks
jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientGetCodingSession: mockClientGetCodingSession,
  clientGetSessionData: mockClientGetSessionData,
  clientGetUser: mockClientGetUser,
}));

// Dynamic import after mocks
const { useCodingSessionEditorData } = await import(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData'
);

// Helper functions
function resetMocks(): void {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockClientGetCodingSession.mockReset();
  mockClientGetSessionData.mockReset();
  mockClientGetUser.mockReset();
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

describe('useCodingSessionEditorData', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('parameter validation', () => {
    it('returns error when projectId is missing', () => {
      const { result } = renderHook(() => useCodingSessionEditorData(undefined, 'session-001'));

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project ID and Session ID are required');
      }
    });

    it('returns error when sessionId is missing', () => {
      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', undefined)
      );

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project ID and Session ID are required');
      }
    });
  });

  describe('authentication', () => {
    it('returns unauthorized when not authenticated', () => {
      setMockAuth(undefined, false);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('unauthorized');
      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You must be logged in to edit sessions');
      }
    });

    it('returns unauthorized when login is undefined', () => {
      setMockAuth(undefined, true);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('unauthorized');
    });
  });

  describe('data loading', () => {
    beforeEach(() => {
      setMockAuth(createMockAuthenticatedLogin(), true);
    });

    it('starts in loading state', () => {
      // Don't resolve the promise yet
      mockClientGetCodingSession.mockReturnValue(new Promise(() => {}));

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('loading');
    });

    it('returns error when session is not found', async () => {
      mockClientGetCodingSession.mockResolvedValue({ success: false });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Coding session not found');
      }
    });

    it('returns unauthorized when user does not own the project', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: {
          codingSessionPkId: 1,
          sessionId: 'session-001',
          storageKey: 'session-001.json.gz',
        },
      });

      // User doesn't own 'other-project'
      const { result } = renderHook(() =>
        useCodingSessionEditorData('other-project', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('unauthorized');
      });

      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You do not have permission to edit this session');
      }
    });

    it('returns error when storageKey is missing', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: {
          codingSessionPkId: 1,
          sessionId: 'session-001',
          storageKey: undefined,
        },
      });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Session content not available');
      }
    });

    it('returns error when session data fails to load', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: {
          codingSessionPkId: 1,
          sessionId: 'session-001',
          storageKey: 'session-001.json.gz',
          userPkId: 1,
        },
      });
      mockClientGetSessionData.mockResolvedValue(null);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Failed to load session content');
      }
    });

    it('returns ready state with data when all loads succeed', async () => {
      const mockSession = {
        codingSessionPkId: 1,
        sessionId: 'session-001',
        storageKey: 'session-001.json.gz',
        userPkId: 1,
      };
      const mockSessionData = { messages: [], summary: 'Test summary' };

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetSessionData.mockResolvedValue(mockSessionData);
      mockClientGetUser.mockResolvedValue({
        success: true,
        data: { username: 'testuser' },
      });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectId).toBe('coding-with-claude');
        expect(result.current.data.session).toEqual(mockSession);
        expect(result.current.data.sessionData).toEqual(mockSessionData);
        expect(result.current.data.projectOwnerUsername).toBe('testuser');
      }
    });

    it('handles user fetch failure gracefully', async () => {
      const mockSession = {
        codingSessionPkId: 1,
        sessionId: 'session-001',
        storageKey: 'session-001.json.gz',
        userPkId: 1,
      };
      const mockSessionData = { messages: [], summary: 'Test summary' };

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetSessionData.mockResolvedValue(mockSessionData);
      mockClientGetUser.mockResolvedValue({ success: false });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectOwnerUsername).toBeUndefined();
      }
    });

    it('catches and handles exceptions', async () => {
      mockClientGetCodingSession.mockRejectedValue(new Error('Network error'));

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Network error');
      }
    });
  });
});

Version 2

/**
 * Unit tests for useCodingSessionEditorData hook
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { renderHook, waitFor } from '@testing-library/react';
import type { CwcLogin, CwcCodingSession, CwcSessionData, CwcUser } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';

// API response types for proper mock typing
type GetCodingSessionResult =
  | { success: true; data: CwcCodingSession }
  | { success: false };
type GetUserResult = { success: true; data: CwcUser } | { success: false };

// Helper to create mock CodingSession
function createMockCodingSession(overrides?: Partial<CwcCodingSession>): CwcCodingSession {
  return {
    codingSessionPkId: 1,
    enabled: true,
    createdDate: '2024-01-01T00:00:00Z',
    modifiedDate: '2024-01-01T00:00:00Z',
    userPkId: 1,
    projectPkId: 1,
    description: 'Test session',
    published: true,
    sessionId: 'session-001',
    storageKey: 'session-001.json.gz',
    startTimestamp: '2024-01-01T00:00:00Z',
    endTimestamp: '2024-01-01T01:00:00Z',
    gitBranch: 'main',
    model: 'claude-3-opus',
    messageCount: 10,
    filesModifiedCount: 5,
    ...overrides,
  };
}

// Helper to create mock SessionData
function createMockSessionData(overrides?: Partial<CwcSessionData>): CwcSessionData {
  return {
    formatVersion: '1.0.0',
    sessionId: 'session-001',
    projectSessionFolder: 'coding-with-claude',
    startTimestamp: '2024-01-01T00:00:00.000Z',
    endTimestamp: '2024-01-01T01:00:00.000Z',
    model: 'claude-3-opus',
    gitBranch: 'main',
    summary: 'Test summary',
    cwd: '/path/to/project',
    claudeCodeVersion: '2.0.42',
    messages: [],
    files: [],
    stats: {
      totalMessages: 10,
      userMessages: 5,
      assistantMessages: 5,
      filesModified: 3,
      totalTokens: { input: 1000, output: 2000, cacheRead: 0, cacheCreation: 0 },
    },
    ...overrides,
  };
}

// Default mock config
const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock login states
const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;

// Mock API functions with proper types
const mockClientGetCodingSession = jest.fn<
  (apiUri: string, sessionId: string) => Promise<GetCodingSessionResult>
>();
const mockClientGetSessionData = jest.fn<
  (contentUri: string, projectId: string, storageKey: string) => Promise<CwcSessionData | null>
>();
const mockClientGetUser = jest.fn<(apiUri: string, userPkId: number) => Promise<GetUserResult>>();

// Set up ESM mocks
jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientGetCodingSession: mockClientGetCodingSession,
  clientGetSessionData: mockClientGetSessionData,
  clientGetUser: mockClientGetUser,
}));

// Dynamic import after mocks
const { useCodingSessionEditorData } = await import(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData'
);

// Helper functions
function resetMocks(): void {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockClientGetCodingSession.mockReset();
  mockClientGetSessionData.mockReset();
  mockClientGetUser.mockReset();
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

describe('useCodingSessionEditorData', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('parameter validation', () => {
    it('returns error when projectId is missing', () => {
      const { result } = renderHook(() => useCodingSessionEditorData(undefined, 'session-001'));

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project ID and Session ID are required');
      }
    });

    it('returns error when sessionId is missing', () => {
      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', undefined)
      );

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project ID and Session ID are required');
      }
    });
  });

  describe('authentication', () => {
    it('returns unauthorized when not authenticated', () => {
      setMockAuth(undefined, false);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('unauthorized');
      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You must be logged in to edit sessions');
      }
    });

    it('returns unauthorized when login is undefined', () => {
      setMockAuth(undefined, true);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('unauthorized');
    });
  });

  describe('data loading', () => {
    beforeEach(() => {
      setMockAuth(createMockAuthenticatedLogin(), true);
    });

    it('starts in loading state', () => {
      // Don't resolve the promise yet
      mockClientGetCodingSession.mockReturnValue(new Promise(() => {}));

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('loading');
    });

    it('returns error when session is not found', async () => {
      mockClientGetCodingSession.mockResolvedValue({ success: false });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Coding session not found');
      }
    });

    it('returns unauthorized when user does not own the project', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });

      // User doesn't own 'other-project'
      const { result } = renderHook(() =>
        useCodingSessionEditorData('other-project', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('unauthorized');
      });

      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You do not have permission to edit this session');
      }
    });

    it('returns error when storageKey is missing', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession({ storageKey: '' }),
      });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Session content not available');
      }
    });

    it('returns error when session data fails to load', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });
      mockClientGetSessionData.mockResolvedValue(null);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Failed to load session content');
      }
    });

    it('returns ready state with data when all loads succeed', async () => {
      const mockSession = createMockCodingSession();
      const mockData = createMockSessionData();

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetSessionData.mockResolvedValue(mockData);
      mockClientGetUser.mockResolvedValue({
        success: true,
        data: { userPkId: 1, username: 'testuser' } as CwcUser,
      });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectId).toBe('coding-with-claude');
        expect(result.current.data.session).toEqual(mockSession);
        expect(result.current.data.sessionData).toEqual(mockData);
        expect(result.current.data.projectOwnerUsername).toBe('testuser');
      }
    });

    it('handles user fetch failure gracefully', async () => {
      const mockSession = createMockCodingSession();
      const mockData = createMockSessionData();

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetSessionData.mockResolvedValue(mockData);
      mockClientGetUser.mockResolvedValue({ success: false });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectOwnerUsername).toBeUndefined();
      }
    });

    it('catches and handles exceptions', async () => {
      mockClientGetCodingSession.mockRejectedValue(new Error('Network error'));

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Network error');
      }
    });
  });
});

Version 3

/**
 * Unit tests for useCodingSessionEditorData hook
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { renderHook, waitFor } from '@testing-library/react';
import type { CwcCodingSession, CwcSessionData, CwcUser } from 'cwc-types';
import {
  mockConfig,
  mockGuestLogin,
  createMockAuthenticatedLogin,
  createMockCodingSession,
  createMockSessionData,
} from '@/__tests__/mocks';

// API response types for proper mock typing
type GetCodingSessionResult =
  | { success: true; data: CwcCodingSession }
  | { success: false };
type GetUserResult = { success: true; data: CwcUser } | { success: false };

// Mutable state for mocks
let mockLogin = mockGuestLogin;
let mockIsAuthenticated = false;

// Mock API functions with proper types
const mockClientGetCodingSession = jest.fn<
  (apiUri: string, sessionId: string) => Promise<GetCodingSessionResult>
>();
const mockClientGetSessionData = jest.fn<
  (contentUri: string, projectId: string, storageKey: string) => Promise<CwcSessionData | null>
>();
const mockClientGetUser = jest.fn<(apiUri: string, userPkId: number) => Promise<GetUserResult>>();

// Set up ESM mocks
jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientGetCodingSession: mockClientGetCodingSession,
  clientGetSessionData: mockClientGetSessionData,
  clientGetUser: mockClientGetUser,
}));

// Dynamic import after mocks
const { useCodingSessionEditorData } = await import(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData'
);

// Helper functions
function resetMocks(): void {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockClientGetCodingSession.mockReset();
  mockClientGetSessionData.mockReset();
  mockClientGetUser.mockReset();
}

function setMockAuth(login: typeof mockLogin, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

describe('useCodingSessionEditorData', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('parameter validation', () => {
    it('returns error when projectId is missing', () => {
      const { result } = renderHook(() => useCodingSessionEditorData(undefined, 'session-001'));

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project ID and Session ID are required');
      }
    });

    it('returns error when sessionId is missing', () => {
      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', undefined)
      );

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project ID and Session ID are required');
      }
    });
  });

  describe('authentication', () => {
    it('returns unauthorized when not authenticated', () => {
      setMockAuth(undefined as unknown as typeof mockLogin, false);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('unauthorized');
      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You must be logged in to edit sessions');
      }
    });

    it('returns unauthorized when login is undefined', () => {
      setMockAuth(undefined as unknown as typeof mockLogin, true);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('unauthorized');
    });
  });

  describe('data loading', () => {
    beforeEach(() => {
      setMockAuth(createMockAuthenticatedLogin(), true);
    });

    it('starts in loading state', () => {
      // Don't resolve the promise yet
      mockClientGetCodingSession.mockReturnValue(new Promise(() => {}));

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      expect(result.current.status).toBe('loading');
    });

    it('returns error when session is not found', async () => {
      mockClientGetCodingSession.mockResolvedValue({ success: false });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Coding session not found');
      }
    });

    it('returns unauthorized when user does not own the project', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });

      // User doesn't own 'other-project'
      const { result } = renderHook(() =>
        useCodingSessionEditorData('other-project', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('unauthorized');
      });

      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You do not have permission to edit this session');
      }
    });

    it('returns error when storageKey is missing', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession({ storageKey: '' }),
      });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Session content not available');
      }
    });

    it('returns error when session data fails to load', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });
      mockClientGetSessionData.mockResolvedValue(null);

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Failed to load session content');
      }
    });

    it('returns ready state with data when all loads succeed', async () => {
      const mockSession = createMockCodingSession();
      const mockData = createMockSessionData();

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetSessionData.mockResolvedValue(mockData);
      mockClientGetUser.mockResolvedValue({
        success: true,
        data: { userPkId: 1, username: 'testuser' } as CwcUser,
      });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectId).toBe('coding-with-claude');
        expect(result.current.data.session).toEqual(mockSession);
        expect(result.current.data.sessionData).toEqual(mockData);
        expect(result.current.data.projectOwnerUsername).toBe('testuser');
      }
    });

    it('handles user fetch failure gracefully', async () => {
      const mockSession = createMockCodingSession();
      const mockData = createMockSessionData();

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetSessionData.mockResolvedValue(mockData);
      mockClientGetUser.mockResolvedValue({ success: false });

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectOwnerUsername).toBeUndefined();
      }
    });

    it('catches and handles exceptions', async () => {
      mockClientGetCodingSession.mockRejectedValue(new Error('Network error'));

      const { result } = renderHook(() =>
        useCodingSessionEditorData('coding-with-claude', 'session-001')
      );

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Network error');
      }
    });
  });
});

Version 4 (latest)

/**
 * Unit tests for useCodingSessionEditorData hook
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { renderHook, waitFor } from '@testing-library/react';
import type { CwcCodingSession, CwcProject, CwcSessionData, CwcUser } from 'cwc-types';
import {
  mockConfig,
  mockGuestLogin,
  createMockAuthenticatedLogin,
  createMockCodingSession,
  createMockSessionData,
  createMockProject,
} from '@/__tests__/mocks';

// API response types for proper mock typing
type GetCodingSessionResult =
  | { success: true; data: CwcCodingSession }
  | { success: false };
type GetProjectResult = { success: true; data: CwcProject } | { success: false };
type GetUserResult = { success: true; data: CwcUser } | { success: false };

// Mutable state for mocks
let mockLogin = mockGuestLogin;
let mockIsAuthenticated = false;

// Mock API functions with proper types
const mockClientGetCodingSession = jest.fn<
  (apiUri: string, codingSessionPkId: number) => Promise<GetCodingSessionResult>
>();
const mockClientGetProjectByPkId = jest.fn<
  (apiUri: string, projectPkId: number) => Promise<GetProjectResult>
>();
const mockClientGetSessionData = jest.fn<
  (contentUri: string, projectId: string, storageKey: string) => Promise<CwcSessionData | null>
>();
const mockClientGetUser = jest.fn<(apiUri: string, userPkId: number) => Promise<GetUserResult>>();

// Set up ESM mocks
jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: jest.fn(),
    logoff: jest.fn(),
  }),
  useConfig: () => mockConfig,
}));

jest.unstable_mockModule('@/clientApi', () => ({
  clientGetCodingSession: mockClientGetCodingSession,
  clientGetProjectByPkId: mockClientGetProjectByPkId,
  clientGetSessionData: mockClientGetSessionData,
  clientGetUser: mockClientGetUser,
}));

// Dynamic import after mocks
const { useCodingSessionEditorData } = await import(
  '@/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData'
);

// Helper functions
function resetMocks(): void {
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockClientGetCodingSession.mockReset();
  mockClientGetProjectByPkId.mockReset();
  mockClientGetSessionData.mockReset();
  mockClientGetUser.mockReset();
}

function setMockAuth(login: typeof mockLogin, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

describe('useCodingSessionEditorData', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('parameter validation', () => {
    it('returns error when codingSessionPkId is missing', () => {
      const { result } = renderHook(() => useCodingSessionEditorData(undefined));

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('codingSessionPkId is required');
      }
    });

    it('returns error when codingSessionPkId is not a valid number', () => {
      const { result } = renderHook(() => useCodingSessionEditorData('not-a-number'));

      expect(result.current.status).toBe('error');
      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Invalid codingSessionPkId');
      }
    });
  });

  describe('authentication', () => {
    it('returns unauthorized when not authenticated', () => {
      setMockAuth(undefined as unknown as typeof mockLogin, false);

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      expect(result.current.status).toBe('unauthorized');
      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You must be logged in to edit sessions');
      }
    });

    it('returns unauthorized when login is undefined', () => {
      setMockAuth(undefined as unknown as typeof mockLogin, true);

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      expect(result.current.status).toBe('unauthorized');
    });
  });

  describe('data loading', () => {
    beforeEach(() => {
      setMockAuth(createMockAuthenticatedLogin(), true);
    });

    it('starts in loading state', () => {
      // Don't resolve the promise yet
      mockClientGetCodingSession.mockReturnValue(new Promise(() => {}));

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      expect(result.current.status).toBe('loading');
    });

    it('returns error when session is not found', async () => {
      mockClientGetCodingSession.mockResolvedValue({ success: false });

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Coding session not found');
      }
    });

    it('returns error when project is not found', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });
      mockClientGetProjectByPkId.mockResolvedValue({ success: false });

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Project not found');
      }
    });

    it('returns unauthorized when user does not own the project', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });
      // Return a project that the user doesn't own
      mockClientGetProjectByPkId.mockResolvedValue({
        success: true,
        data: createMockProject({ projectId: 'other-project' }),
      });

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('unauthorized');
      });

      if (result.current.status === 'unauthorized') {
        expect(result.current.message).toBe('You do not have permission to edit this session');
      }
    });

    it('returns error when storageKey is missing', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession({ storageKey: '' }),
      });
      mockClientGetProjectByPkId.mockResolvedValue({
        success: true,
        data: createMockProject(),
      });

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Session content not available');
      }
    });

    it('returns error when session data fails to load', async () => {
      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: createMockCodingSession(),
      });
      mockClientGetProjectByPkId.mockResolvedValue({
        success: true,
        data: createMockProject(),
      });
      mockClientGetSessionData.mockResolvedValue(null);

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Failed to load session content');
      }
    });

    it('returns ready state with data when all loads succeed', async () => {
      const mockSession = createMockCodingSession();
      const mockProject = createMockProject();
      const mockData = createMockSessionData();

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetProjectByPkId.mockResolvedValue({
        success: true,
        data: mockProject,
      });
      mockClientGetSessionData.mockResolvedValue(mockData);
      mockClientGetUser.mockResolvedValue({
        success: true,
        data: { userPkId: 1, username: 'testuser' } as CwcUser,
      });

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectId).toBe(mockProject.projectId);
        expect(result.current.data.session).toEqual(mockSession);
        expect(result.current.data.sessionData).toEqual(mockData);
        expect(result.current.data.projectOwnerUsername).toBe('testuser');
      }
    });

    it('handles user fetch failure gracefully', async () => {
      const mockSession = createMockCodingSession();
      const mockProject = createMockProject();
      const mockData = createMockSessionData();

      mockClientGetCodingSession.mockResolvedValue({
        success: true,
        data: mockSession,
      });
      mockClientGetProjectByPkId.mockResolvedValue({
        success: true,
        data: mockProject,
      });
      mockClientGetSessionData.mockResolvedValue(mockData);
      mockClientGetUser.mockResolvedValue({ success: false });

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('ready');
      });

      if (result.current.status === 'ready') {
        expect(result.current.data.projectOwnerUsername).toBeUndefined();
      }
    });

    it('catches and handles exceptions', async () => {
      mockClientGetCodingSession.mockRejectedValue(new Error('Network error'));

      const { result } = renderHook(() => useCodingSessionEditorData('42'));

      await waitFor(() => {
        expect(result.current.status).toBe('error');
      });

      if (result.current.status === 'error') {
        expect(result.current.error).toBe('Network error');
      }
    });
  });
});

packages/cwc-website/src/__tests__/views/client/Logon/Logon.test.tsx

3 versions

Version 1

/**
 * Unit tests for Logon page
 */

import { describe, it, expect, beforeEach } from '@jest/globals';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import Logon from '@/views/client/Logon/Logon';
import {
  mockNavigate,
  mockUseFetcher,
  createMockFetcher,
  setMockLocationState,
  resetRouterMocks,
  setMockAuth,
  resetMockAuth,
  mockSetLoginFromJwt,
  createMockAuthenticatedLogin,
} from '../../../mocks';

// Mock the server module
jest.mock('@/server', () => ({
  logon: jest.fn(),
}));

// Mock UI components
jest.mock('@/components/ui/button', () => ({
  Button: ({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
    <button {...props}>{children}</button>
  ),
}));

jest.mock('@/components/ui/card', () => ({
  Card: ({ children, className }: { children: React.ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
  CardContent: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
  CardDescription: ({ children }: { children: React.ReactNode }) => <p>{children}</p>,
  CardHeader: ({ children, className }: { children: React.ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
  CardTitle: ({ children, className }: { children: React.ReactNode; className?: string }) => (
    <h2 className={className}>{children}</h2>
  ),
}));

describe('Logon', () => {
  beforeEach(() => {
    resetRouterMocks();
    resetMockAuth();
    // Default to idle fetcher
    mockUseFetcher.mockReturnValue(createMockFetcher());
  });

  describe('rendering', () => {
    it('renders the logon form', () => {
      render(<Logon />);

      expect(screen.getByRole('heading', { name: 'Logon' })).toBeInTheDocument();
      expect(screen.getByLabelText('Username')).toBeInTheDocument();
      expect(screen.getByLabelText('Password')).toBeInTheDocument();
      expect(screen.getByLabelText('Keep me logged in')).toBeInTheDocument();
      expect(screen.getByRole('button', { name: 'Logon' })).toBeInTheDocument();
    });

    it('shows description text', () => {
      render(<Logon />);

      expect(screen.getByText('Enter your credentials to access your account')).toBeInTheDocument();
    });
  });

  describe('form input', () => {
    it('allows entering username', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const usernameInput = screen.getByLabelText('Username');
      await user.type(usernameInput, 'testuser');

      expect(usernameInput).toHaveValue('testuser');
    });

    it('allows entering password', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const passwordInput = screen.getByLabelText('Password');
      await user.type(passwordInput, 'testpass123');

      expect(passwordInput).toHaveValue('testpass123');
    });

    it('allows toggling keep logged in checkbox', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const checkbox = screen.getByLabelText('Keep me logged in');
      expect(checkbox).not.toBeChecked();

      await user.click(checkbox);
      expect(checkbox).toBeChecked();

      await user.click(checkbox);
      expect(checkbox).not.toBeChecked();
    });
  });

  describe('form submission', () => {
    it('calls fetcher.submit with form data on submit', async () => {
      const user = userEvent.setup();
      const mockSubmit = jest.fn();
      mockUseFetcher.mockReturnValue({
        ...createMockFetcher(),
        submit: mockSubmit,
      });

      render(<Logon />);

      await user.type(screen.getByLabelText('Username'), 'testuser');
      await user.type(screen.getByLabelText('Password'), 'testpass');
      await user.click(screen.getByRole('button', { name: 'Logon' }));

      expect(mockSubmit).toHaveBeenCalledTimes(1);
      const formData = mockSubmit.mock.calls[0][0] as FormData;
      expect(formData.get('username')).toBe('testuser');
      expect(formData.get('password')).toBe('testpass');
      expect(formData.get('deviceId')).toBe('test-device-id');
      expect(formData.get('kulo')).toBe('false');
    });

    it('submits with kulo=true when keep logged in is checked', async () => {
      const user = userEvent.setup();
      const mockSubmit = jest.fn();
      mockUseFetcher.mockReturnValue({
        ...createMockFetcher(),
        submit: mockSubmit,
      });

      render(<Logon />);

      await user.type(screen.getByLabelText('Username'), 'testuser');
      await user.type(screen.getByLabelText('Password'), 'testpass');
      await user.click(screen.getByLabelText('Keep me logged in'));
      await user.click(screen.getByRole('button', { name: 'Logon' }));

      const formData = mockSubmit.mock.calls[0][0] as FormData;
      expect(formData.get('kulo')).toBe('true');
    });

    it('shows "Logging on..." when submitting', () => {
      mockUseFetcher.mockReturnValue(createMockFetcher({ state: 'submitting' }));

      render(<Logon />);

      expect(screen.getByRole('button', { name: 'Logging on...' })).toBeInTheDocument();
      expect(screen.getByRole('button')).toBeDisabled();
    });

    it('disables inputs while submitting', () => {
      mockUseFetcher.mockReturnValue(createMockFetcher({ state: 'submitting' }));

      render(<Logon />);

      expect(screen.getByLabelText('Username')).toBeDisabled();
      expect(screen.getByLabelText('Password')).toBeDisabled();
      expect(screen.getByLabelText('Keep me logged in')).toBeDisabled();
    });
  });

  describe('successful login', () => {
    it('calls setLoginFromJwt with the JWT from response', async () => {
      mockUseFetcher.mockReturnValue(
        createMockFetcher({
          state: 'idle',
          data: { success: true, jwt: 'new-jwt-token' },
        })
      );

      render(<Logon />);

      await waitFor(() => {
        expect(mockSetLoginFromJwt).toHaveBeenCalledWith('new-jwt-token');
      });
    });

    it('navigates to home page after successful login', async () => {
      mockSetLoginFromJwt.mockReturnValue(true);
      mockUseFetcher.mockReturnValue(
        createMockFetcher({
          state: 'idle',
          data: { success: true, jwt: 'new-jwt-token' },
        })
      );

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
      });
    });

    it('navigates to return URL after successful login', async () => {
      setMockLocationState({ from: '/project/coding-with-claude' });
      mockSetLoginFromJwt.mockReturnValue(true);
      mockUseFetcher.mockReturnValue(
        createMockFetcher({
          state: 'idle',
          data: { success: true, jwt: 'new-jwt-token' },
        })
      );

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/project/coding-with-claude', { replace: true });
      });
    });

    it('shows error if JWT decoding fails', async () => {
      mockSetLoginFromJwt.mockReturnValue(false);
      mockUseFetcher.mockReturnValue(
        createMockFetcher({
          state: 'idle',
          data: { success: true, jwt: 'invalid-jwt' },
        })
      );

      render(<Logon />);

      await waitFor(() => {
        expect(screen.getByText('Failed to decode authentication token')).toBeInTheDocument();
      });
    });
  });

  describe('failed login', () => {
    it('shows error message from server in non-prod mode', async () => {
      mockUseFetcher.mockReturnValue(
        createMockFetcher({
          state: 'idle',
          data: { success: false, errorMessage: 'User not found' },
        })
      );

      render(<Logon />);

      await waitFor(() => {
        expect(screen.getByText('User not found')).toBeInTheDocument();
      });
    });
  });

  describe('already authenticated', () => {
    it('redirects to home if already authenticated', async () => {
      setMockAuth(createMockAuthenticatedLogin(), true);

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
      });
    });

    it('redirects to return URL if already authenticated', async () => {
      setMockLocationState({ from: '/project/my-project' });
      setMockAuth(createMockAuthenticatedLogin(), true);

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/project/my-project', { replace: true });
      });
    });
  });
});

Version 2

/**
 * Unit tests for Logon page
 */

import { jest, describe, it, expect, beforeEach, beforeAll } from '@jest/globals';
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import type { ReactNode } from 'react';
import type { CwcLogin } from 'cwc-types';
import type { CwcWebsiteConfig } from '@/config';

// Default mock config
const mockConfig: CwcWebsiteConfig = {
  runtimeEnvironment: 'unit',
  isProd: false,
  isDev: false,
  isTest: false,
  isUnit: true,
  isE2E: false,
  appUrl: 'http://localhost:3000',
  authUriInternal: 'http://localhost:5005/auth/v1',
  apiUriInternal: 'http://localhost:5040/api/v1',
  contentUriInternal: 'http://localhost:5050/content/v1',
  authUriExternal: 'http://localhost:5005/auth/v1',
  apiUriExternal: 'http://localhost:5040/api/v1',
  contentUriExternal: 'http://localhost:5050/content/v1',
  debugMode: false,
  websiteContentMode: 'Full',
};

// Mock login state
const mockGuestLogin: CwcLogin = {
  username: 'Guest',
  deviceId: 'test-device-id',
  userJwtId: '',
  loginType: 'cwc',
  kulo: false,
  ownedProjects: [],
  isGuestUser: true,
  autoLogonAttempted: true,
  authToken: undefined,
};

function createMockAuthenticatedLogin(overrides?: Partial<CwcLogin>): CwcLogin {
  return {
    username: 'testuser',
    deviceId: 'test-device-id',
    userJwtId: 'jwt-123',
    loginType: 'cwc',
    kulo: false,
    ownedProjects: ['coding-with-claude'],
    isGuestUser: false,
    autoLogonAttempted: true,
    authToken: 'mock-jwt-token',
    ...overrides,
  };
}

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;
let mockLocationState: Record<string, unknown> = {};

// Mock functions
const mockNavigate = jest.fn();
const mockSetLoginFromJwt = jest.fn((jwt: string) => {
  if (jwt) {
    mockLogin = createMockAuthenticatedLogin({ authToken: jwt });
    mockIsAuthenticated = true;
    return true;
  }
  return false;
});
const mockLogoff = jest.fn();
const mockSubmit = jest.fn();

// Mock fetcher factory
function createMockFetcher(overrides?: { state?: 'idle' | 'submitting' | 'loading'; data?: unknown }) {
  return {
    state: overrides?.state ?? 'idle',
    data: overrides?.data ?? undefined,
    submit: mockSubmit,
    load: jest.fn(),
    Form: ({ children }: { children: ReactNode }) => <form>{children}</form>,
    formData: undefined,
    formAction: undefined,
    formEncType: undefined,
    formMethod: undefined,
  };
}

let mockFetcher = createMockFetcher();

// Set up ESM mocks before importing Logon
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: mockLocationState,
    key: 'default',
  }),
  useFetcher: () => mockFetcher,
  Link: ({ to, children, ...props }: { to: string; children: ReactNode }) => (
    <a href={to} {...props}>
      {children}
    </a>
  ),
}));

jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: mockSetLoginFromJwt,
    logoff: mockLogoff,
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
}));

jest.unstable_mockModule('@/server', () => ({
  logon: jest.fn(),
}));

jest.unstable_mockModule('@/components/ui/button', () => ({
  Button: ({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
    <button {...props}>{children}</button>
  ),
}));

jest.unstable_mockModule('@/components/ui/card', () => ({
  Card: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
  CardContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
  CardDescription: ({ children }: { children: ReactNode }) => <p>{children}</p>,
  CardHeader: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
  CardTitle: ({ children, className }: { children: ReactNode; className?: string }) => (
    <h2 className={className}>{children}</h2>
  ),
}));

// Dynamic import of component after mocks are set up
const { default: Logon } = await import('@/views/client/Logon/Logon');

// Helper functions for tests
function resetMocks(): void {
  mockNavigate.mockReset();
  mockSetLoginFromJwt.mockReset();
  mockLogoff.mockReset();
  mockSubmit.mockReset();
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockLocationState = {};
  mockFetcher = createMockFetcher();
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

function setMockLocationState(state: Record<string, unknown>): void {
  mockLocationState = state;
}

function setMockFetcherState(overrides: { state?: 'idle' | 'submitting' | 'loading'; data?: unknown }): void {
  mockFetcher = createMockFetcher(overrides);
}

describe('Logon', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('rendering', () => {
    it('renders the logon form', () => {
      render(<Logon />);

      expect(screen.getByRole('heading', { name: 'Logon' })).toBeInTheDocument();
      expect(screen.getByLabelText('Username')).toBeInTheDocument();
      expect(screen.getByLabelText('Password')).toBeInTheDocument();
      expect(screen.getByLabelText('Keep me logged in')).toBeInTheDocument();
      expect(screen.getByRole('button', { name: 'Logon' })).toBeInTheDocument();
    });

    it('shows description text', () => {
      render(<Logon />);

      expect(screen.getByText('Enter your credentials to access your account')).toBeInTheDocument();
    });
  });

  describe('form input', () => {
    it('allows entering username', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const usernameInput = screen.getByLabelText('Username');
      await user.type(usernameInput, 'testuser');

      expect(usernameInput).toHaveValue('testuser');
    });

    it('allows entering password', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const passwordInput = screen.getByLabelText('Password');
      await user.type(passwordInput, 'testpass123');

      expect(passwordInput).toHaveValue('testpass123');
    });

    it('allows toggling keep logged in checkbox', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const checkbox = screen.getByLabelText('Keep me logged in');
      expect(checkbox).not.toBeChecked();

      await user.click(checkbox);
      expect(checkbox).toBeChecked();

      await user.click(checkbox);
      expect(checkbox).not.toBeChecked();
    });
  });

  describe('form submission', () => {
    it('calls fetcher.submit with form data on submit', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      await user.type(screen.getByLabelText('Username'), 'testuser');
      await user.type(screen.getByLabelText('Password'), 'testpass');
      await user.click(screen.getByRole('button', { name: 'Logon' }));

      expect(mockSubmit).toHaveBeenCalledTimes(1);
      const formData = mockSubmit.mock.calls[0][0] as FormData;
      expect(formData.get('username')).toBe('testuser');
      expect(formData.get('password')).toBe('testpass');
      expect(formData.get('deviceId')).toBe('test-device-id');
      expect(formData.get('kulo')).toBe('false');
    });

    it('submits with kulo=true when keep logged in is checked', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      await user.type(screen.getByLabelText('Username'), 'testuser');
      await user.type(screen.getByLabelText('Password'), 'testpass');
      await user.click(screen.getByLabelText('Keep me logged in'));
      await user.click(screen.getByRole('button', { name: 'Logon' }));

      const formData = mockSubmit.mock.calls[0][0] as FormData;
      expect(formData.get('kulo')).toBe('true');
    });

    it('shows "Logging on..." when submitting', () => {
      setMockFetcherState({ state: 'submitting' });
      render(<Logon />);

      expect(screen.getByRole('button', { name: 'Logging on...' })).toBeInTheDocument();
      expect(screen.getByRole('button')).toBeDisabled();
    });

    it('disables inputs while submitting', () => {
      setMockFetcherState({ state: 'submitting' });
      render(<Logon />);

      expect(screen.getByLabelText('Username')).toBeDisabled();
      expect(screen.getByLabelText('Password')).toBeDisabled();
      expect(screen.getByLabelText('Keep me logged in')).toBeDisabled();
    });
  });

  describe('successful login', () => {
    it('calls setLoginFromJwt with the JWT from response', async () => {
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'new-jwt-token' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(mockSetLoginFromJwt).toHaveBeenCalledWith('new-jwt-token');
      });
    });

    it('navigates to home page after successful login', async () => {
      mockSetLoginFromJwt.mockReturnValue(true);
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'new-jwt-token' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
      });
    });

    it('navigates to return URL after successful login', async () => {
      setMockLocationState({ from: '/project/coding-with-claude' });
      mockSetLoginFromJwt.mockReturnValue(true);
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'new-jwt-token' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/project/coding-with-claude', { replace: true });
      });
    });

    it('shows error if JWT decoding fails', async () => {
      mockSetLoginFromJwt.mockReturnValue(false);
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'invalid-jwt' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(screen.getByText('Failed to decode authentication token')).toBeInTheDocument();
      });
    });
  });

  describe('failed login', () => {
    it('shows error message from server in non-prod mode', async () => {
      setMockFetcherState({
        state: 'idle',
        data: { success: false, errorMessage: 'User not found' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(screen.getByText('User not found')).toBeInTheDocument();
      });
    });
  });

  describe('already authenticated', () => {
    it('redirects to home if already authenticated', async () => {
      setMockAuth(createMockAuthenticatedLogin(), true);

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
      });
    });

    it('redirects to return URL if already authenticated', async () => {
      setMockLocationState({ from: '/project/my-project' });
      setMockAuth(createMockAuthenticatedLogin(), true);

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/project/my-project', { replace: true });
      });
    });
  });
});

Version 3 (latest)

/**
 * Unit tests for Logon page
 */

import { jest, describe, it, expect, beforeEach } from '@jest/globals';
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import type { ReactNode } from 'react';
import type { CwcLogin } from 'cwc-types';
import {
  mockConfig,
  mockGuestLogin,
  createMockAuthenticatedLogin,
  createMockFetcher,
  MockLink,
} from '@/__tests__/mocks';

// Mutable state for mocks
let mockLogin: CwcLogin | undefined = mockGuestLogin;
let mockIsAuthenticated = false;
let mockLocationState: Record<string, unknown> = {};

// Mock functions
const mockNavigate = jest.fn();
const mockSubmit = jest.fn();
const mockSetLoginFromJwt = jest.fn((jwt: string) => {
  if (jwt) {
    mockLogin = createMockAuthenticatedLogin({ authToken: jwt });
    mockIsAuthenticated = true;
    return true;
  }
  return false;
});
const mockLogoff = jest.fn();

// Mock fetcher factory using shared helper
function createTestFetcher(overrides?: { state?: 'idle' | 'submitting' | 'loading'; data?: unknown }) {
  return createMockFetcher({
    ...overrides,
    submit: mockSubmit,
  });
}

let mockFetcher = createTestFetcher();

// Set up ESM mocks before importing Logon
jest.unstable_mockModule('react-router', () => ({
  useNavigate: () => mockNavigate,
  useLocation: () => ({
    pathname: '/',
    search: '',
    hash: '',
    state: mockLocationState,
    key: 'default',
  }),
  useFetcher: () => mockFetcher,
  Link: MockLink,
}));

jest.unstable_mockModule('@/hooks', () => ({
  useAuth: () => ({
    isAuthenticated: mockIsAuthenticated,
    login: mockLogin,
    setLoginFromJwt: mockSetLoginFromJwt,
    logoff: mockLogoff,
  }),
  useConfig: () => mockConfig,
  getDeviceId: () => 'test-device-id',
}));

jest.unstable_mockModule('@/server', () => ({
  logon: jest.fn(),
}));

jest.unstable_mockModule('@/components/ui/button', () => ({
  Button: ({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
    <button {...props}>{children}</button>
  ),
}));

jest.unstable_mockModule('@/components/ui/card', () => ({
  Card: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
  CardContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
  CardDescription: ({ children }: { children: ReactNode }) => <p>{children}</p>,
  CardHeader: ({ children, className }: { children: ReactNode; className?: string }) => (
    <div className={className}>{children}</div>
  ),
  CardTitle: ({ children, className }: { children: ReactNode; className?: string }) => (
    <h2 className={className}>{children}</h2>
  ),
}));

// Dynamic import of component after mocks are set up
const { default: Logon } = await import('@/views/client/Logon/Logon');

// Helper functions for tests
function resetMocks(): void {
  mockNavigate.mockReset();
  mockSetLoginFromJwt.mockReset();
  mockLogoff.mockReset();
  mockSubmit.mockReset();
  mockLogin = mockGuestLogin;
  mockIsAuthenticated = false;
  mockLocationState = {};
  mockFetcher = createTestFetcher();
}

function setMockAuth(login: CwcLogin | undefined, isAuthenticated: boolean): void {
  mockLogin = login;
  mockIsAuthenticated = isAuthenticated;
}

function setMockLocationState(state: Record<string, unknown>): void {
  mockLocationState = state;
}

function setMockFetcherState(overrides: { state?: 'idle' | 'submitting' | 'loading'; data?: unknown }): void {
  mockFetcher = createTestFetcher(overrides);
}

describe('Logon', () => {
  beforeEach(() => {
    resetMocks();
  });

  describe('rendering', () => {
    it('renders the logon form', () => {
      render(<Logon />);

      expect(screen.getByRole('heading', { name: 'Logon' })).toBeInTheDocument();
      expect(screen.getByLabelText('Username')).toBeInTheDocument();
      expect(screen.getByLabelText('Password')).toBeInTheDocument();
      expect(screen.getByLabelText('Keep me logged in')).toBeInTheDocument();
      expect(screen.getByRole('button', { name: 'Logon' })).toBeInTheDocument();
    });

    it('shows description text', () => {
      render(<Logon />);

      expect(screen.getByText('Enter your credentials to access your account')).toBeInTheDocument();
    });
  });

  describe('form input', () => {
    it('allows entering username', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const usernameInput = screen.getByLabelText('Username');
      await user.type(usernameInput, 'testuser');

      expect(usernameInput).toHaveValue('testuser');
    });

    it('allows entering password', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const passwordInput = screen.getByLabelText('Password');
      await user.type(passwordInput, 'testpass123');

      expect(passwordInput).toHaveValue('testpass123');
    });

    it('allows toggling keep logged in checkbox', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      const checkbox = screen.getByLabelText('Keep me logged in');
      expect(checkbox).not.toBeChecked();

      await user.click(checkbox);
      expect(checkbox).toBeChecked();

      await user.click(checkbox);
      expect(checkbox).not.toBeChecked();
    });
  });

  describe('form submission', () => {
    it('calls fetcher.submit with form data on submit', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      await user.type(screen.getByLabelText('Username'), 'testuser');
      await user.type(screen.getByLabelText('Password'), 'testpass');
      await user.click(screen.getByRole('button', { name: 'Logon' }));

      expect(mockSubmit).toHaveBeenCalledTimes(1);
      const formData = mockSubmit.mock.calls[0][0] as FormData;
      expect(formData.get('username')).toBe('testuser');
      expect(formData.get('password')).toBe('testpass');
      expect(formData.get('deviceId')).toBe('test-device-id');
      expect(formData.get('kulo')).toBe('false');
    });

    it('submits with kulo=true when keep logged in is checked', async () => {
      const user = userEvent.setup();
      render(<Logon />);

      await user.type(screen.getByLabelText('Username'), 'testuser');
      await user.type(screen.getByLabelText('Password'), 'testpass');
      await user.click(screen.getByLabelText('Keep me logged in'));
      await user.click(screen.getByRole('button', { name: 'Logon' }));

      const formData = mockSubmit.mock.calls[0][0] as FormData;
      expect(formData.get('kulo')).toBe('true');
    });

    it('shows "Logging on..." when submitting', () => {
      setMockFetcherState({ state: 'submitting' });
      render(<Logon />);

      expect(screen.getByRole('button', { name: 'Logging on...' })).toBeInTheDocument();
      expect(screen.getByRole('button')).toBeDisabled();
    });

    it('disables inputs while submitting', () => {
      setMockFetcherState({ state: 'submitting' });
      render(<Logon />);

      expect(screen.getByLabelText('Username')).toBeDisabled();
      expect(screen.getByLabelText('Password')).toBeDisabled();
      expect(screen.getByLabelText('Keep me logged in')).toBeDisabled();
    });
  });

  describe('successful login', () => {
    it('calls setLoginFromJwt with the JWT from response', async () => {
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'new-jwt-token' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(mockSetLoginFromJwt).toHaveBeenCalledWith('new-jwt-token');
      });
    });

    it('navigates to home page after successful login', async () => {
      mockSetLoginFromJwt.mockReturnValue(true);
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'new-jwt-token' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
      });
    });

    it('navigates to return URL after successful login', async () => {
      setMockLocationState({ from: '/project/coding-with-claude' });
      mockSetLoginFromJwt.mockReturnValue(true);
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'new-jwt-token' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/project/coding-with-claude', { replace: true });
      });
    });

    it('shows error if JWT decoding fails', async () => {
      mockSetLoginFromJwt.mockReturnValue(false);
      setMockFetcherState({
        state: 'idle',
        data: { success: true, jwt: 'invalid-jwt' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(screen.getByText('Failed to decode authentication token')).toBeInTheDocument();
      });
    });
  });

  describe('failed login', () => {
    it('shows error message from server in non-prod mode', async () => {
      setMockFetcherState({
        state: 'idle',
        data: { success: false, errorMessage: 'User not found' },
      });

      render(<Logon />);

      await waitFor(() => {
        expect(screen.getByText('User not found')).toBeInTheDocument();
      });
    });
  });

  describe('already authenticated', () => {
    it('redirects to home if already authenticated', async () => {
      setMockAuth(createMockAuthenticatedLogin(), true);

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/', { replace: true });
      });
    });

    it('redirects to return URL if already authenticated', async () => {
      setMockLocationState({ from: '/project/my-project' });
      setMockAuth(createMockAuthenticatedLogin(), true);

      render(<Logon />);

      await waitFor(() => {
        expect(mockNavigate).toHaveBeenCalledWith('/project/my-project', { replace: true });
      });
    });
  });
});

packages/cwc-website/src/clientApi/clientApi.ts

2 versions

Version 1

/**
 * Client-side API utilities for browser-based data fetching
 *
 * These functions use external URLs and browser-compatible libraries (pako for gzip).
 * Use these for client-side data fetching after component mount.
 *
 * For server-side operations (loaders/actions), use the functions in /server instead.
 */

import pako from 'pako';
import type { CwcCodingSession, CwcSessionData } from 'cwc-types';

/**
 * API response types (same as server)
 */
export type ClientApiSuccessResponse<T> = {
  success: true;
  data: T;
};

export type ClientApiErrorResponse = {
  success: false;
  errorCode: string;
  errorMessage: string;
};

export type ClientApiResponse<T> = ClientApiSuccessResponse<T> | ClientApiErrorResponse;

/**
 * Content API response type
 */
type ContentApiSuccessResponse = {
  success: true;
  data: string; // Base64-encoded gzipped JSON
};

type ContentApiErrorResponse = {
  success: false;
  errorCode: string;
  errorMessage: string;
};

type ContentApiResponse = ContentApiSuccessResponse | ContentApiErrorResponse;

/**
 * POST to cwc-api endpoint (client-side, no auth)
 */
export async function clientApiPost<TPayload, TResult>(
  apiUri: string,
  endpoint: string,
  payload: TPayload
): Promise<ClientApiResponse<TResult>> {
  try {
    const url = `${apiUri}${endpoint}`;

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return {
        success: false,
        errorCode: 'HTTP_ERROR',
        errorMessage: `HTTP ${response.status}: ${response.statusText}`,
      };
    }

    return (await response.json()) as ClientApiResponse<TResult>;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    return {
      success: false,
      errorCode: 'FETCH_ERROR',
      errorMessage,
    };
  }
}

/**
 * POST to cwc-api endpoint with authentication (client-side)
 */
export async function clientApiPostAuth<TPayload, TResult>(
  apiUri: string,
  endpoint: string,
  payload: TPayload,
  jwt: string
): Promise<ClientApiResponse<TResult>> {
  try {
    const url = `${apiUri}${endpoint}`;

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwt}`,
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return {
        success: false,
        errorCode: 'HTTP_ERROR',
        errorMessage: `HTTP ${response.status}: ${response.statusText}`,
      };
    }

    return (await response.json()) as ClientApiResponse<TResult>;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    return {
      success: false,
      errorCode: 'FETCH_ERROR',
      errorMessage,
    };
  }
}

/**
 * Get a single coding session by sessionId (client-side)
 */
export async function clientGetCodingSession(
  apiUri: string,
  sessionId: string
): Promise<ClientApiResponse<CwcCodingSession>> {
  return clientApiPost<{ sessionId: string }, CwcCodingSession>(apiUri, '/codingSession/get', {
    sessionId,
  });
}

/**
 * Fetch session data from cwc-content (client-side)
 *
 * Uses pako for browser-compatible gzip decompression.
 */
export async function clientGetSessionData(
  contentUri: string,
  projectId: string,
  storageKey: string
): Promise<CwcSessionData | undefined> {
  try {
    const url = `${contentUri}/coding-session/get`;

    const payload = {
      projectId,
      filename: storageKey,
    };

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      console.error(`[clientApi] HTTP ${response.status}: ${response.statusText}`);
      return undefined;
    }

    const result = (await response.json()) as ContentApiResponse;

    if (!result.success) {
      console.error(`[clientApi] Error: ${result.errorMessage}`);
      return undefined;
    }

    // Decode base64 and decompress using pako
    const binaryString = atob(result.data);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }

    const decompressed = pako.ungzip(bytes, { to: 'string' });
    const sessionData = JSON.parse(decompressed) as CwcSessionData;

    return sessionData;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    console.error('[clientApi] Failed to fetch session data:', errorMessage);
    return undefined;
  }
}

/**
 * Safe user type (public info only)
 */
type SafeUser = {
  userPkId: number;
  username: string;
};

/**
 * Get user info (client-side)
 */
export async function clientGetUser(
  apiUri: string,
  userPkId: number
): Promise<ClientApiResponse<SafeUser>> {
  return clientApiPost<{ userPkId: number }, SafeUser>(apiUri, '/user/get', { userPkId });
}

/**
 * Update coding session metadata (client-side with auth)
 */
export async function clientUpdateCodingSession(
  apiUri: string,
  codingSessionPkId: number,
  updates: { description?: string; published?: boolean },
  jwt: string
): Promise<ClientApiResponse<CwcCodingSession>> {
  return clientApiPostAuth<
    { codingSessionPkId: number; description?: string; published?: boolean },
    CwcCodingSession
  >(apiUri, '/codingSession/update', { codingSessionPkId, ...updates }, jwt);
}

/**
 * Delete coding session (client-side with auth)
 *
 * Deletes both content and metadata.
 */
export async function clientDeleteCodingSession(
  apiUri: string,
  contentUri: string,
  codingSessionPkId: number,
  projectId: string,
  storageKey: string,
  jwt: string
): Promise<{ success: true } | { success: false; error: string }> {
  // Delete content file first
  const contentResult = await clientDeleteSessionContent(contentUri, projectId, storageKey, jwt);

  if (!contentResult.success) {
    return { success: false, error: `Failed to delete content: ${contentResult.error}` };
  }

  // Delete metadata from cwc-api
  const apiResult = await clientApiPostAuth<{ codingSessionPkId: number }, void>(
    apiUri,
    '/codingSession/delete',
    { codingSessionPkId },
    jwt
  );

  if (!apiResult.success) {
    return { success: false, error: `Failed to delete session: ${apiResult.errorMessage}` };
  }

  return { success: true };
}

/**
 * Update session content (client-side with auth)
 *
 * Uses pako for browser-compatible gzip compression.
 */
export async function clientUpdateSessionContent(
  contentUri: string,
  projectId: string,
  storageKey: string,
  sessionData: CwcSessionData,
  jwt: string
): Promise<{ success: true } | { success: false; error: string }> {
  try {
    const url = `${contentUri}/coding-session/put`;

    // Gzip and base64 encode using pako
    const jsonString = JSON.stringify(sessionData);
    const compressed = pako.gzip(jsonString);

    // Convert Uint8Array to base64
    let binary = '';
    for (let i = 0; i < compressed.length; i++) {
      binary += String.fromCharCode(compressed[i] as number);
    }
    const base64Data = btoa(binary);

    const payload = {
      projectId,
      filename: storageKey,
      data: base64Data,
    };

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwt}`,
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
    }

    const result = (await response.json()) as ContentApiResponse;

    if (!result.success) {
      return { success: false, error: result.errorMessage };
    }

    return { success: true };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    console.error('[clientApi] Failed to update session content:', errorMessage);
    return { success: false, error: errorMessage };
  }
}

/**
 * Delete session content (client-side with auth)
 */
async function clientDeleteSessionContent(
  contentUri: string,
  projectId: string,
  storageKey: string,
  jwt: string
): Promise<{ success: true } | { success: false; error: string }> {
  try {
    const url = `${contentUri}/coding-session/delete`;

    const payload = {
      projectId,
      filename: storageKey,
    };

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwt}`,
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
    }

    const result = (await response.json()) as ContentApiResponse;

    if (!result.success) {
      return { success: false, error: result.errorMessage };
    }

    return { success: true };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    console.error('[clientApi] Failed to delete session content:', errorMessage);
    return { success: false, error: errorMessage };
  }
}

Version 2 (latest)

/**
 * Client-side API utilities for browser-based data fetching
 *
 * These functions use external URLs and browser-compatible libraries (pako for gzip).
 * Use these for client-side data fetching after component mount.
 *
 * For server-side operations (loaders/actions), use the functions in /server instead.
 */

import pako from 'pako';
import type { CwcCodingSession, CwcProject, CwcSessionData } from 'cwc-types';

/**
 * API response types (same as server)
 */
export type ClientApiSuccessResponse<T> = {
  success: true;
  data: T;
};

export type ClientApiErrorResponse = {
  success: false;
  errorCode: string;
  errorMessage: string;
};

export type ClientApiResponse<T> = ClientApiSuccessResponse<T> | ClientApiErrorResponse;

/**
 * Content API response type
 */
type ContentApiSuccessResponse = {
  success: true;
  data: string; // Base64-encoded gzipped JSON
};

type ContentApiErrorResponse = {
  success: false;
  errorCode: string;
  errorMessage: string;
};

type ContentApiResponse = ContentApiSuccessResponse | ContentApiErrorResponse;

/**
 * POST to cwc-api endpoint (client-side, no auth)
 */
export async function clientApiPost<TPayload, TResult>(
  apiUri: string,
  endpoint: string,
  payload: TPayload
): Promise<ClientApiResponse<TResult>> {
  try {
    const url = `${apiUri}${endpoint}`;

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return {
        success: false,
        errorCode: 'HTTP_ERROR',
        errorMessage: `HTTP ${response.status}: ${response.statusText}`,
      };
    }

    return (await response.json()) as ClientApiResponse<TResult>;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    return {
      success: false,
      errorCode: 'FETCH_ERROR',
      errorMessage,
    };
  }
}

/**
 * POST to cwc-api endpoint with authentication (client-side)
 */
export async function clientApiPostAuth<TPayload, TResult>(
  apiUri: string,
  endpoint: string,
  payload: TPayload,
  jwt: string
): Promise<ClientApiResponse<TResult>> {
  try {
    const url = `${apiUri}${endpoint}`;

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwt}`,
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return {
        success: false,
        errorCode: 'HTTP_ERROR',
        errorMessage: `HTTP ${response.status}: ${response.statusText}`,
      };
    }

    return (await response.json()) as ClientApiResponse<TResult>;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    return {
      success: false,
      errorCode: 'FETCH_ERROR',
      errorMessage,
    };
  }
}

/**
 * Get a single coding session by codingSessionPkId (client-side)
 */
export async function clientGetCodingSession(
  apiUri: string,
  codingSessionPkId: number
): Promise<ClientApiResponse<CwcCodingSession>> {
  return clientApiPost<{ codingSessionPkId: number }, CwcCodingSession>(
    apiUri,
    '/codingSession/get',
    { codingSessionPkId }
  );
}

/**
 * Get a single project by projectPkId (client-side)
 */
export async function clientGetProjectByPkId(
  apiUri: string,
  projectPkId: number
): Promise<ClientApiResponse<CwcProject>> {
  return clientApiPost<{ projectPkId: number }, CwcProject>(apiUri, '/project/get', {
    projectPkId,
  });
}

/**
 * Fetch session data from cwc-content (client-side)
 *
 * Uses pako for browser-compatible gzip decompression.
 */
export async function clientGetSessionData(
  contentUri: string,
  projectId: string,
  storageKey: string
): Promise<CwcSessionData | undefined> {
  try {
    const url = `${contentUri}/coding-session/get`;

    const payload = {
      projectId,
      filename: storageKey,
    };

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      console.error(`[clientApi] HTTP ${response.status}: ${response.statusText}`);
      return undefined;
    }

    const result = (await response.json()) as ContentApiResponse;

    if (!result.success) {
      console.error(`[clientApi] Error: ${result.errorMessage}`);
      return undefined;
    }

    // Decode base64 and decompress using pako
    const binaryString = atob(result.data);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }

    const decompressed = pako.ungzip(bytes, { to: 'string' });
    const sessionData = JSON.parse(decompressed) as CwcSessionData;

    return sessionData;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    console.error('[clientApi] Failed to fetch session data:', errorMessage);
    return undefined;
  }
}

/**
 * Safe user type (public info only)
 */
type SafeUser = {
  userPkId: number;
  username: string;
};

/**
 * Get user info (client-side)
 */
export async function clientGetUser(
  apiUri: string,
  userPkId: number
): Promise<ClientApiResponse<SafeUser>> {
  return clientApiPost<{ userPkId: number }, SafeUser>(apiUri, '/user/get', { userPkId });
}

/**
 * Update coding session metadata (client-side with auth)
 */
export async function clientUpdateCodingSession(
  apiUri: string,
  codingSessionPkId: number,
  updates: { description?: string; published?: boolean },
  jwt: string
): Promise<ClientApiResponse<CwcCodingSession>> {
  return clientApiPostAuth<
    { codingSessionPkId: number; description?: string; published?: boolean },
    CwcCodingSession
  >(apiUri, '/codingSession/update', { codingSessionPkId, ...updates }, jwt);
}

/**
 * Delete coding session (client-side with auth)
 *
 * Deletes both content and metadata.
 */
export async function clientDeleteCodingSession(
  apiUri: string,
  contentUri: string,
  codingSessionPkId: number,
  projectId: string,
  storageKey: string,
  jwt: string
): Promise<{ success: true } | { success: false; error: string }> {
  // Delete content file first
  const contentResult = await clientDeleteSessionContent(contentUri, projectId, storageKey, jwt);

  if (!contentResult.success) {
    return { success: false, error: `Failed to delete content: ${contentResult.error}` };
  }

  // Delete metadata from cwc-api
  const apiResult = await clientApiPostAuth<{ codingSessionPkId: number }, void>(
    apiUri,
    '/codingSession/delete',
    { codingSessionPkId },
    jwt
  );

  if (!apiResult.success) {
    return { success: false, error: `Failed to delete session: ${apiResult.errorMessage}` };
  }

  return { success: true };
}

/**
 * Update session content (client-side with auth)
 *
 * Uses pako for browser-compatible gzip compression.
 */
export async function clientUpdateSessionContent(
  contentUri: string,
  projectId: string,
  storageKey: string,
  sessionData: CwcSessionData,
  jwt: string
): Promise<{ success: true } | { success: false; error: string }> {
  try {
    const url = `${contentUri}/coding-session/put`;

    // Gzip and base64 encode using pako
    const jsonString = JSON.stringify(sessionData);
    const compressed = pako.gzip(jsonString);

    // Convert Uint8Array to base64
    let binary = '';
    for (let i = 0; i < compressed.length; i++) {
      binary += String.fromCharCode(compressed[i] as number);
    }
    const base64Data = btoa(binary);

    const payload = {
      projectId,
      filename: storageKey,
      data: base64Data,
    };

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwt}`,
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
    }

    const result = (await response.json()) as ContentApiResponse;

    if (!result.success) {
      return { success: false, error: result.errorMessage };
    }

    return { success: true };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    console.error('[clientApi] Failed to update session content:', errorMessage);
    return { success: false, error: errorMessage };
  }
}

/**
 * Delete session content (client-side with auth)
 */
async function clientDeleteSessionContent(
  contentUri: string,
  projectId: string,
  storageKey: string,
  jwt: string
): Promise<{ success: true } | { success: false; error: string }> {
  try {
    const url = `${contentUri}/coding-session/delete`;

    const payload = {
      projectId,
      filename: storageKey,
    };

    const request = new Request(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${jwt}`,
      },
      body: JSON.stringify(payload),
    });

    const response = await fetch(request);

    if (!response.ok) {
      return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
    }

    const result = (await response.json()) as ContentApiResponse;

    if (!result.success) {
      return { success: false, error: result.errorMessage };
    }

    return { success: true };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    console.error('[clientApi] Failed to delete session content:', errorMessage);
    return { success: false, error: errorMessage };
  }
}

packages/cwc-website/src/clientApi/index.ts

2 versions

Version 1

export {
  clientGetCodingSession,
  clientGetSessionData,
  clientGetUser,
  clientUpdateCodingSession,
  clientDeleteCodingSession,
  clientUpdateSessionContent,
  type ClientApiResponse,
} from './clientApi';

Version 2 (latest)

export {
  clientGetCodingSession,
  clientGetProjectByPkId,
  clientGetSessionData,
  clientGetUser,
  clientUpdateCodingSession,
  clientDeleteCodingSession,
  clientUpdateSessionContent,
  type ClientApiResponse,
} from './clientApi';

packages/cwc-website/src/layouts/ClientLayout/ClientLayout.tsx

import type { ReactNode } from 'react';
import { Outlet, useLoaderData } from 'react-router';
import { loadConfig, type CwcWebsiteConfig } from '@/config';

/**
 * Minimal layout for client-rendered pages
 *
 * Provides config via outlet context (same as SiteLayout) but without
 * header/footer. Used for full-viewport pages like CodingSessionEditor.
 */
export async function loader(): Promise<CwcWebsiteConfig> {
  return loadConfig();
}

export function ClientLayout(): ReactNode {
  const config = useLoaderData<typeof loader>();

  return <Outlet context={{ config }} />;
}

// Default export required for React Router v7 route modules
export default ClientLayout;

packages/cwc-website/src/layouts/ClientLayout/index.ts

export { ClientLayout } from './ClientLayout';

packages/cwc-website/src/prerender/prerender.ts

2 versions

Version 1

/**
 * Pre-render route discovery for static site generation
 *
 * This module discovers all routes that need to be pre-rendered at build time.
 * It fetches project and session data from the API to generate paths for dynamic routes.
 *
 * Usage in react-router.config.ts:
 *   import { discoverRoutes } from './src/prerender';
 *   export default { prerender: discoverRoutes } satisfies Config;
 */

import { loadConfig } from '../config';
import { fetchAllProjects, fetchSessionsForProject, fetchSessionData } from './prerenderApi';
import { calculatePagination } from './sessionPagination';

/**
 * Parameters passed to the prerender function by React Router
 */
type PrerenderParams = {
  getStaticPaths: () => string[];
};

/**
 * Discover all routes to pre-render
 *
 * Returns an array of all URL paths that should be pre-rendered at build time.
 *
 * Static routes are discovered automatically via getStaticPaths().
 * Dynamic routes (projects, sessions) are discovered by fetching from the API.
 *
 * In 'Minimal' content mode, only static routes are pre-rendered (no projects/sessions).
 */
export async function discoverRoutes({ getStaticPaths }: PrerenderParams): Promise<string[]> {
  console.log('[prerender] Starting route discovery...');
  const startTime = Date.now();

  // Load config to check content mode
  const config = loadConfig();
  console.log(`[prerender] Content mode: ${config.websiteContentMode}`);

  // 1. Get static routes automatically (/, /about, /privacy-policy)
  const staticPaths = getStaticPaths();
  console.log(`[prerender] Static paths: ${staticPaths.join(', ')}`);

  // For Minimal mode, only pre-render static routes (no projects/sessions)
  if (config.websiteContentMode === 'Minimal') {
    // Filter out /projects from static paths in Minimal mode
    const minimalPaths = staticPaths.filter(p => p !== '/projects');
    const elapsed = Date.now() - startTime;
    console.log(`[prerender] Minimal mode - skipping project/session discovery`);
    console.log(`[prerender] Route discovery complete in ${elapsed}ms`);
    console.log(`[prerender] Total paths to pre-render: ${minimalPaths.length}`);
    return minimalPaths;
  }

  // 2. Add /projects (list page)
  const allPaths: string[] = [...staticPaths, '/projects'];

  // 3. Fetch all projects and their sessions
  const projects = await fetchAllProjects();

  for (const project of projects) {
    // Add project page
    const projectPath = `/project/${project.projectId}`;
    allPaths.push(projectPath);

    // Fetch sessions for this project
    const sessions = await fetchSessionsForProject(project.projectPkId);

    for (const session of sessions) {
      // Base session path (page 1) - uses codingSessionPkId for simplified URL
      const sessionBasePath = `/session/${session.codingSessionPkId}`;
      allPaths.push(sessionBasePath);

      // Fetch session data to calculate pagination
      if (session.storageKey) {
        const sessionData = await fetchSessionData(project.projectId, session.storageKey);

        if (sessionData) {
          const paginationInfo = calculatePagination(session.codingSessionPkId, sessionData);

          // Add paginated routes (page 2+)
          for (let page = 2; page <= paginationInfo.totalPages; page++) {
            allPaths.push(`${sessionBasePath}/page/${page}`);
          }

          if (paginationInfo.totalPages > 1) {
            console.log(
              `[prerender]   Session ${session.codingSessionPkId}: ${paginationInfo.totalPages} pages`
            );
          }
        }
      }
    }

    console.log(
      `[prerender] Project "${project.projectId}": ${sessions.length} sessions`
    );
  }

  const elapsed = Date.now() - startTime;
  console.log(`[prerender] Route discovery complete in ${elapsed}ms`);
  console.log(`[prerender] Total paths to pre-render: ${allPaths.length}`);

  return allPaths;
}

Version 2 (latest)

/**
 * Pre-render route discovery for static site generation
 *
 * This module discovers all routes that need to be pre-rendered at build time.
 * It fetches project and session data from the API to generate paths for dynamic routes.
 *
 * Usage in react-router.config.ts:
 *   import { discoverRoutes } from './src/prerender';
 *   export default { prerender: discoverRoutes } satisfies Config;
 */

import { loadConfig } from '../config';
import { fetchAllProjects, fetchSessionsForProject, fetchSessionData } from './prerenderApi';
import { calculatePagination } from './sessionPagination';

/**
 * Parameters passed to the prerender function by React Router
 */
type PrerenderParams = {
  getStaticPaths: () => string[];
};

/**
 * Discover all routes to pre-render
 *
 * Returns an array of all URL paths that should be pre-rendered at build time.
 *
 * Static routes are discovered automatically via getStaticPaths().
 * Dynamic routes (projects, sessions) are discovered by fetching from the API.
 *
 * In 'Minimal' content mode, only static routes are pre-rendered (no projects/sessions).
 */
export async function discoverRoutes({ getStaticPaths }: PrerenderParams): Promise<string[]> {
  console.log('[prerender] Starting route discovery...');
  const startTime = Date.now();

  // Load config to check content mode
  const config = loadConfig();
  console.log(`[prerender] Content mode: ${config.websiteContentMode}`);

  // 1. Get static routes automatically (/, /about, /privacy-policy)
  const staticPaths = getStaticPaths();
  console.log(`[prerender] Static paths: ${staticPaths.join(', ')}`);

  // For Minimal mode, only pre-render static routes (no projects/sessions)
  if (config.websiteContentMode === 'Minimal') {
    // Filter out /projects from static paths in Minimal mode
    const minimalPaths = staticPaths.filter((p) => p !== '/projects');
    const elapsed = Date.now() - startTime;
    console.log(`[prerender] Minimal mode - skipping project/session discovery`);
    console.log(`[prerender] Route discovery complete in ${elapsed}ms`);
    console.log(`[prerender] Total paths to pre-render: ${minimalPaths.length}`);
    return minimalPaths;
  }

  // 2. Add /projects (list page)
  const allPaths: string[] = [...staticPaths, '/projects'];

  // 3. Fetch all projects and their sessions
  const projects = await fetchAllProjects();

  for (const project of projects) {
    // Add project page
    const projectPath = `/project/${project.projectId}`;
    allPaths.push(projectPath);

    // Fetch sessions for this project
    const sessions = await fetchSessionsForProject(project.projectPkId);

    for (const session of sessions) {
      // Base session path (page 1) - uses codingSessionPkId for simplified URL
      const sessionBasePath = `/session/${session.codingSessionPkId}`;
      allPaths.push(sessionBasePath);

      // Fetch session data to calculate pagination
      if (session.storageKey) {
        const sessionData = await fetchSessionData(project.projectId, session.storageKey);

        if (sessionData) {
          const paginationInfo = calculatePagination(session.codingSessionPkId, sessionData);

          // Add paginated routes (page 2+)
          for (let page = 2; page <= paginationInfo.totalPages; page++) {
            allPaths.push(`${sessionBasePath}/page/${page}`);
          }

          if (paginationInfo.totalPages > 1) {
            console.log(
              `[prerender]   Session ${session.codingSessionPkId}: ${paginationInfo.totalPages} pages`
            );
          }
        }
      }
    }

    console.log(`[prerender] Project "${project.projectId}": ${sessions.length} sessions`);
  }

  const elapsed = Date.now() - startTime;
  console.log(`[prerender] Route discovery complete in ${elapsed}ms`);
  console.log(`[prerender] Total paths to pre-render: ${allPaths.length}`);

  return allPaths;
}

packages/cwc-website/src/prerender/sessionPagination.ts

2 versions

Version 1

/**
 * Session pagination calculation for SSG
 *
 * Calculates page boundaries based on estimated HTML size to ensure
 * each pre-rendered page is within the target size (~150KB).
 */

import type { CwcSessionData, CwcSessionMessage, CwcSessionContent } from 'cwc-types';

/**
 * Target page size in bytes (150KB - midpoint of 100-200KB target)
 */
const TARGET_PAGE_SIZE_BYTES = 150 * 1024;

/**
 * Page range definition - which messages are on each page
 */
export type PageRange = {
  startIndex: number;
  endIndex: number; // Inclusive
};

/**
 * Pagination information for a session
 */
export type SessionPaginationInfo = {
  codingSessionPkId: number;
  totalPages: number;
  totalMessages: number;
  pageRanges: PageRange[];
};

/**
 * Build-time cache for pagination info
 *
 * Used to share pagination data between route discovery and loader execution
 * during SSG builds. Keyed by codingSessionPkId (number).
 */
const paginationCache = new Map<number, SessionPaginationInfo>();

/**
 * Cache pagination info for a session
 */
export function cacheSessionPagination(info: SessionPaginationInfo): void {
  paginationCache.set(info.codingSessionPkId, info);
}

/**
 * Get cached pagination info for a session
 */
export function getCachedPagination(codingSessionPkId: number): SessionPaginationInfo | undefined {
  return paginationCache.get(codingSessionPkId);
}

/**
 * Clear the pagination cache (for testing)
 */
export function clearPaginationCache(): void {
  paginationCache.clear();
}

/**
 * Estimate the HTML size of a content block
 *
 * Uses heuristics to approximate how large the rendered HTML will be:
 * - Text content: raw length * 1.5 (markdown expansion)
 * - Tool use: 300 bytes overhead + JSON.stringify(input).length
 * - Tool result: 200 bytes overhead + content.length
 */
function estimateContentSize(content: CwcSessionContent): number {
  switch (content.type) {
    case 'text':
      // Markdown typically expands to ~1.5x the raw text size when rendered
      return content.text.length * 1.5;

    case 'tool_use':
      // Tool invocations have wrapper HTML plus the JSON input
      return 300 + JSON.stringify(content.input).length;

    case 'tool_result':
      // Tool results have wrapper HTML plus the output content
      return 200 + content.content.length;

    default:
      return 0;
  }
}

/**
 * Estimate the HTML size of a message
 *
 * Includes base overhead for message wrapper elements plus
 * the estimated size of all content blocks.
 */
function estimateMessageSize(message: CwcSessionMessage): number {
  // Base HTML overhead for message wrapper (card, header, etc.)
  const baseOverhead = 200;

  const contentSize = message.content.reduce(
    (total, content) => total + estimateContentSize(content),
    0
  );

  return baseOverhead + contentSize;
}

/**
 * Calculate pagination for a session based on size targets
 *
 * Splits messages into pages where each page is approximately
 * the target size (150KB by default).
 *
 * @param sessionData - The complete session data
 * @param targetSizeBytes - Target page size in bytes (default: 150KB)
 * @returns Pagination info with page ranges
 */
export function calculatePagination(
  sessionData: CwcSessionData,
  targetSizeBytes: number = TARGET_PAGE_SIZE_BYTES
): SessionPaginationInfo {
  const messages = sessionData.messages;
  const pageRanges: PageRange[] = [];

  if (messages.length === 0) {
    // Empty session - single empty page
    return {
      sessionId: sessionData.sessionId,
      totalPages: 1,
      totalMessages: 0,
      pageRanges: [{ startIndex: 0, endIndex: -1 }],
    };
  }

  let currentPageStart = 0;
  let currentPageSize = 0;

  for (let i = 0; i < messages.length; i++) {
    const messageSize = estimateMessageSize(messages[i]);

    // If adding this message exceeds target, start new page
    // (but always include at least one message per page)
    if (currentPageSize + messageSize > targetSizeBytes && currentPageSize > 0) {
      pageRanges.push({
        startIndex: currentPageStart,
        endIndex: i - 1,
      });
      currentPageStart = i;
      currentPageSize = 0;
    }

    currentPageSize += messageSize;
  }

  // Add the final page
  pageRanges.push({
    startIndex: currentPageStart,
    endIndex: messages.length - 1,
  });

  const info: SessionPaginationInfo = {
    sessionId: sessionData.sessionId,
    totalPages: pageRanges.length,
    totalMessages: messages.length,
    pageRanges,
  };

  // Cache for later use by loaders
  cacheSessionPagination(info);

  return info;
}

/**
 * Get messages for a specific page
 *
 * @param sessionData - The complete session data
 * @param pageNumber - 1-indexed page number
 * @param paginationInfo - Pre-calculated pagination info
 * @returns Messages for the requested page, or empty array if page doesn't exist
 */
export function getMessagesForPage(
  sessionData: CwcSessionData,
  pageNumber: number,
  paginationInfo: SessionPaginationInfo
): CwcSessionMessage[] {
  // Page numbers are 1-indexed
  const pageIndex = pageNumber - 1;

  if (pageIndex < 0 || pageIndex >= paginationInfo.pageRanges.length) {
    return [];
  }

  const range = paginationInfo.pageRanges[pageIndex];
  return sessionData.messages.slice(range.startIndex, range.endIndex + 1);
}

Version 2 (latest)

/**
 * Session pagination calculation for SSG
 *
 * Calculates page boundaries based on estimated HTML size to ensure
 * each pre-rendered page is within the target size (~150KB).
 */

import type { CwcSessionData, CwcSessionMessage, CwcSessionContent } from 'cwc-types';

/**
 * Target page size in bytes (150KB - midpoint of 100-200KB target)
 */
const TARGET_PAGE_SIZE_BYTES = 150 * 1024;

/**
 * Page range definition - which messages are on each page
 */
export type PageRange = {
  startIndex: number;
  endIndex: number; // Inclusive
};

/**
 * Pagination information for a session
 */
export type SessionPaginationInfo = {
  codingSessionPkId: number;
  totalPages: number;
  totalMessages: number;
  pageRanges: PageRange[];
};

/**
 * Build-time cache for pagination info
 *
 * Used to share pagination data between route discovery and loader execution
 * during SSG builds. Keyed by codingSessionPkId (number).
 */
const paginationCache = new Map<number, SessionPaginationInfo>();

/**
 * Cache pagination info for a session
 */
export function cacheSessionPagination(info: SessionPaginationInfo): void {
  paginationCache.set(info.codingSessionPkId, info);
}

/**
 * Get cached pagination info for a session
 */
export function getCachedPagination(codingSessionPkId: number): SessionPaginationInfo | undefined {
  return paginationCache.get(codingSessionPkId);
}

/**
 * Clear the pagination cache (for testing)
 */
export function clearPaginationCache(): void {
  paginationCache.clear();
}

/**
 * Estimate the HTML size of a content block
 *
 * Uses heuristics to approximate how large the rendered HTML will be:
 * - Text content: raw length * 1.5 (markdown expansion)
 * - Tool use: 300 bytes overhead + JSON.stringify(input).length
 * - Tool result: 200 bytes overhead + content.length
 */
function estimateContentSize(content: CwcSessionContent): number {
  switch (content.type) {
    case 'text':
      // Markdown typically expands to ~1.5x the raw text size when rendered
      return content.text.length * 1.5;

    case 'tool_use':
      // Tool invocations have wrapper HTML plus the JSON input
      return 300 + JSON.stringify(content.input).length;

    case 'tool_result':
      // Tool results have wrapper HTML plus the output content
      return 200 + content.content.length;

    default:
      return 0;
  }
}

/**
 * Estimate the HTML size of a message
 *
 * Includes base overhead for message wrapper elements plus
 * the estimated size of all content blocks.
 */
function estimateMessageSize(message: CwcSessionMessage): number {
  // Base HTML overhead for message wrapper (card, header, etc.)
  const baseOverhead = 200;

  const contentSize = message.content.reduce(
    (total, content) => total + estimateContentSize(content),
    0
  );

  return baseOverhead + contentSize;
}

/**
 * Calculate pagination for a session based on size targets
 *
 * Splits messages into pages where each page is approximately
 * the target size (150KB by default).
 *
 * @param codingSessionPkId - The database primary key for caching
 * @param sessionData - The complete session data
 * @param targetSizeBytes - Target page size in bytes (default: 150KB)
 * @returns Pagination info with page ranges
 */
export function calculatePagination(
  codingSessionPkId: number,
  sessionData: CwcSessionData,
  targetSizeBytes: number = TARGET_PAGE_SIZE_BYTES
): SessionPaginationInfo {
  const messages = sessionData.messages;
  const pageRanges: PageRange[] = [];

  if (messages.length === 0) {
    // Empty session - single empty page
    return {
      codingSessionPkId,
      totalPages: 1,
      totalMessages: 0,
      pageRanges: [{ startIndex: 0, endIndex: -1 }],
    };
  }

  let currentPageStart = 0;
  let currentPageSize = 0;

  for (let i = 0; i < messages.length; i++) {
    const messageSize = estimateMessageSize(messages[i]);

    // If adding this message exceeds target, start new page
    // (but always include at least one message per page)
    if (currentPageSize + messageSize > targetSizeBytes && currentPageSize > 0) {
      pageRanges.push({
        startIndex: currentPageStart,
        endIndex: i - 1,
      });
      currentPageStart = i;
      currentPageSize = 0;
    }

    currentPageSize += messageSize;
  }

  // Add the final page
  pageRanges.push({
    startIndex: currentPageStart,
    endIndex: messages.length - 1,
  });

  const info: SessionPaginationInfo = {
    codingSessionPkId,
    totalPages: pageRanges.length,
    totalMessages: messages.length,
    pageRanges,
  };

  // Cache for later use by loaders
  cacheSessionPagination(info);

  return info;
}

/**
 * Get messages for a specific page
 *
 * @param sessionData - The complete session data
 * @param pageNumber - 1-indexed page number
 * @param paginationInfo - Pre-calculated pagination info
 * @returns Messages for the requested page, or empty array if page doesn't exist
 */
export function getMessagesForPage(
  sessionData: CwcSessionData,
  pageNumber: number,
  paginationInfo: SessionPaginationInfo
): CwcSessionMessage[] {
  // Page numbers are 1-indexed
  const pageIndex = pageNumber - 1;

  if (pageIndex < 0 || pageIndex >= paginationInfo.pageRanges.length) {
    return [];
  }

  const range = paginationInfo.pageRanges[pageIndex];
  return sessionData.messages.slice(range.startIndex, range.endIndex + 1);
}

packages/cwc-website/src/routes.ts

3 versions

Version 1

import { type RouteConfig, index, layout, route } from '@react-router/dev/routes';

export default [
  // Standard pages with SiteLayout (header, footer)
  layout('layouts/SiteLayout/SiteLayout.tsx', [
    index('views/Home/Home.tsx'),
    route('about', 'views/About/About.tsx'),
    route('logon', 'views/Logon/Logon.tsx'),
    route('privacy-policy', 'views/PrivacyPolicy/PrivacyPolicy.tsx'),
    route('projects', 'views/ProjectList/ProjectList.tsx'),
    route('project/:projectId', 'views/Project/Project.tsx'),
  ]),

  // CodingSessionEditor - client-side rendered, wrapped with ClientLayout for config context
  // NOTE: Must come before the session route to match correctly
  layout('layouts/ClientLayout/ClientLayout.tsx', [
    route(
      'project/:projectId/session/:sessionId/edit',
      'views/CodingSessionEditor/CodingSessionEditor.tsx'
    ),
  ]),

  // CodingSession pages - dedicated full-viewport layout (no SiteLayout)
  route('project/:projectId/session/:sessionId', 'views/CodingSession/CodingSession.tsx'),
  route(
    'project/:projectId/session/:sessionId/page/:pageNumber',
    'views/CodingSession/CodingSessionPage.tsx'
  ),
] satisfies RouteConfig;

Version 2

import { type RouteConfig, index, layout, route } from '@react-router/dev/routes';

export default [
  // Server-loaded pages with SiteLayout (header, footer)
  layout('layouts/SiteLayout/SiteLayout.tsx', [
    index('views/server/Home/Home.tsx'),
    route('about', 'views/server/About/About.tsx'),
    route('privacy-policy', 'views/server/PrivacyPolicy/PrivacyPolicy.tsx'),
    route('projects', 'views/server/ProjectList/ProjectList.tsx'),
    route('project/:projectId', 'views/server/Project/Project.tsx'),
    // Client-loaded page with SiteLayout
    route('logon', 'views/client/Logon/Logon.tsx'),
  ]),

  // CodingSessionEditor - client-side rendered, wrapped with ClientLayout for config context
  // NOTE: Must come before the session route to match correctly
  layout('layouts/ClientLayout/ClientLayout.tsx', [
    route(
      'project/:projectId/session/:sessionId/edit',
      'views/client/CodingSessionEditor/CodingSessionEditor.tsx'
    ),
  ]),

  // Server-loaded full-viewport pages (both files in CodingSession folder)
  route('project/:projectId/session/:sessionId', 'views/server/CodingSession/CodingSession.tsx'),
  route(
    'project/:projectId/session/:sessionId/page/:pageNumber',
    'views/server/CodingSession/CodingSessionPage.tsx'
  ),
] satisfies RouteConfig;

Version 3 (latest)

import { type RouteConfig, index, layout, route } from '@react-router/dev/routes';

export default [
  // Server-loaded pages with SiteLayout (header, footer)
  layout('layouts/SiteLayout/SiteLayout.tsx', [
    index('views/server/Home/Home.tsx'),
    route('about', 'views/server/About/About.tsx'),
    route('privacy-policy', 'views/server/PrivacyPolicy/PrivacyPolicy.tsx'),
    route('projects', 'views/server/ProjectList/ProjectList.tsx'),
    route('project/:projectId', 'views/server/Project/Project.tsx'),
    // Client-loaded page with SiteLayout
    route('logon', 'views/client/Logon/Logon.tsx'),
  ]),

  // CodingSessionEditor - client-side rendered, wrapped with ClientLayout for config context
  layout('layouts/ClientLayout/ClientLayout.tsx', [
    route('session-editor/:codingSessionPkId', 'views/client/CodingSessionEditor/CodingSessionEditor.tsx'),
  ]),

  // Server-loaded full-viewport pages (both files in CodingSession folder)
  route('session/:codingSessionPkId', 'views/server/CodingSession/CodingSession.tsx'),
  route(
    'session/:codingSessionPkId/page/:pageNumber',
    'views/server/CodingSession/CodingSessionPage.tsx'
  ),
] satisfies RouteConfig;

packages/cwc-website/src/server/codingSession.ts

import type { CwcCodingSession } from 'cwc-types';
import { cwcApiPost, type CwcApiResponse } from './cwcApi';

/**
 * List coding session payload
 */
type ListCodingSessionPayload = {
  projectPkId?: number;
  page?: number;
  pageSize?: number;
};

/**
 * Get coding session payload
 */
type GetCodingSessionPayload = {
  codingSessionPkId: number;
};

/**
 * Get list of coding sessions for a project
 *
 * Note: Unauthenticated requests automatically filter to published sessions only
 */
export async function getCodingSessionList(
  projectPkId: number,
  payload: Omit<ListCodingSessionPayload, 'projectPkId'> = {}
): Promise<CwcApiResponse<CwcCodingSession[]>> {
  return cwcApiPost<ListCodingSessionPayload, CwcCodingSession[]>('/codingSession/list', {
    projectPkId,
    ...payload,
  });
}

/**
 * Get a single coding session by codingSessionPkId
 */
export async function getCodingSession(
  codingSessionPkId: number
): Promise<CwcApiResponse<CwcCodingSession>> {
  return cwcApiPost<GetCodingSessionPayload, CwcCodingSession>('/codingSession/get', {
    codingSessionPkId,
  });
}

packages/cwc-website/src/server/index.ts

export { cwcApiPost, type CwcApiResponse, type CwcApiPagination } from './cwcApi';
export {
  logon,
  decodeJwtPayload,
  type LogonPayload,
  type LogonResponse,
  type LogonSuccessResponse,
  type LogonErrorResponse,
  type DecodedJwtClaims,
} from './cwcAuth';
export { getProject, getProjectByPkId, getProjectList } from './project';
export { getCodingSession, getCodingSessionList } from './codingSession';
export { getSessionData } from './sessionContent';
export { getUser, type SafeUser } from './user';
export {
  updateCodingSession,
  deleteCodingSession,
  updateSessionContent,
} from './codingSessionEditor';

packages/cwc-website/src/server/project.ts

import type { CwcProject } from 'cwc-types';
import { cwcApiPost, type CwcApiResponse } from './cwcApi';

/**
 * List project payload
 */
type ListProjectPayload = {
  page?: number;
  pageSize?: number;
};

/**
 * Get project payload - supports lookup by either identifier
 */
type GetProjectPayload = { projectId: string } | { projectPkId: number };

/**
 * Get list of all projects
 */
export async function getProjectList(
  payload: ListProjectPayload = {}
): Promise<CwcApiResponse<CwcProject[]>> {
  return cwcApiPost<ListProjectPayload, CwcProject[]>('/project/list', payload);
}

/**
 * Get a single project by projectId (string natural key)
 */
export async function getProject(projectId: string): Promise<CwcApiResponse<CwcProject>> {
  return cwcApiPost<GetProjectPayload, CwcProject>('/project/get', { projectId });
}

/**
 * Get a single project by projectPkId (integer primary key)
 */
export async function getProjectByPkId(projectPkId: number): Promise<CwcApiResponse<CwcProject>> {
  return cwcApiPost<GetProjectPayload, CwcProject>('/project/get', { projectPkId });
}

packages/cwc-website/src/views/client/CodingSessionEditor/CodingSessionEditor.tsx

2 versions

Version 1

import type { ReactNode } from 'react';
import { useState, useCallback, useRef } from 'react';
import { useNavigate, useParams } from 'react-router';
import type { CwcSessionMessage, CwcSessionContent } from 'cwc-types';
import { ScrollArea } from '@/components/ui/scroll-area';
import { useConfig, useAuth } from '@/hooks';
import {
  clientUpdateCodingSession,
  clientUpdateSessionContent,
  clientDeleteCodingSession,
} from '@/clientApi';
import { EditorToolbar } from './components/EditorToolbar';
import { SessionMetadataEditor } from './components/SessionMetadataEditor';
import { MessageEditor, buildHighlightMap } from './components/MessageEditor';
import { SensitiveDataSearch } from './components/SensitiveDataSearch';
import { useSessionEditor } from './hooks/useSessionEditor';
import { useSensitiveSearch, type SensitiveMatch } from './hooks/useSensitiveSearch';
import { useCodingSessionEditorData } from './hooks/useCodingSessionEditorData';

/**
 * Loading spinner component
 */
function LoadingSpinner(): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
        <p className="text-muted-foreground">Loading session editor...</p>
      </div>
    </div>
  );
}

/**
 * Error display component
 */
function ErrorDisplay({ error, onBack }: { error: string; onBack: () => void }): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center max-w-md">
        <div className="text-destructive text-4xl mb-4">⚠</div>
        <h1 className="text-xl font-semibold mb-2">Error Loading Session</h1>
        <p className="text-muted-foreground mb-4">{error}</p>
        <button
          onClick={onBack}
          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
        >
          Go Back
        </button>
      </div>
    </div>
  );
}

/**
 * Unauthorized display component
 */
function UnauthorizedDisplay({
  message,
  onBack,
}: {
  message: string;
  onBack: () => void;
}): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center max-w-md">
        <div className="text-warning text-4xl mb-4">🔒</div>
        <h1 className="text-xl font-semibold mb-2">Access Denied</h1>
        <p className="text-muted-foreground mb-4">{message}</p>
        <button
          onClick={onBack}
          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
        >
          Go Back
        </button>
      </div>
    </div>
  );
}

/**
 * Coding session editor page (client-side rendered)
 *
 * Allows project owners to edit session metadata, message content,
 * and search for sensitive data.
 *
 * Data is fetched client-side after component mount to ensure
 * proper authentication context is available.
 */
export default function CodingSessionEditor(): ReactNode {
  const { codingSessionPkId } = useParams();
  const navigate = useNavigate();
  const config = useConfig();
  const { login } = useAuth();

  // Load data client-side
  const editorState = useCodingSessionEditorData(codingSessionPkId);

  // Handle back navigation (before data is loaded)
  const handleBack = useCallback(() => {
    navigate('/');
  }, [navigate]);

  // Show loading state
  if (editorState.status === 'loading') {
    return <LoadingSpinner />;
  }

  // Show error state
  if (editorState.status === 'error') {
    return <ErrorDisplay error={editorState.error} onBack={handleBack} />;
  }

  // Show unauthorized state
  if (editorState.status === 'unauthorized') {
    return <UnauthorizedDisplay message={editorState.message} onBack={handleBack} />;
  }

  // Data is ready - render the editor
  const { data } = editorState;

  return (
    <CodingSessionEditorContent
      projectId={data.projectId}
      session={data.session}
      initialSessionData={data.sessionData}
      projectOwnerUsername={data.projectOwnerUsername}
      jwt={login?.authToken ?? ''}
      apiUri={config.apiUriExternal}
      contentUri={config.contentUriExternal}
    />
  );
}

/**
 * Editor content component (extracted for cleaner code)
 */
function CodingSessionEditorContent({
  projectId,
  session,
  initialSessionData,
  projectOwnerUsername,
  jwt,
  apiUri,
  contentUri,
}: {
  projectId: string;
  session: {
    codingSessionPkId: number;
    sessionId: string;
    storageKey: string;
  };
  initialSessionData: Parameters<typeof useSessionEditor>[1];
  projectOwnerUsername?: string;
  jwt: string;
  apiUri: string;
  contentUri: string;
}): ReactNode {
  const navigate = useNavigate();

  // Editor state
  const editor = useSessionEditor(
    session as Parameters<typeof useSessionEditor>[0],
    initialSessionData
  );

  // Sensitive data search
  const sensitiveSearch = useSensitiveSearch(editor.sessionData);

  // Saving state
  const [isSaving, setIsSaving] = useState(false);
  const [saveError, setSaveError] = useState<string | undefined>();

  // Message refs for scroll-to navigation
  const messageRefs = useRef<Map<string, HTMLDivElement>>(new Map());

  // Build highlight map from sensitive matches
  const highlightMap = buildHighlightMap(sensitiveSearch.matches);

  /**
   * Handle save action
   */
  const handleSave = useCallback(async () => {
    setIsSaving(true);
    setSaveError(undefined);

    try {
      // Save metadata if changed
      if (editor.isMetadataDirty) {
        const metadataResult = await clientUpdateCodingSession(
          apiUri,
          session.codingSessionPkId,
          {
            description: editor.description,
            published: editor.published,
          },
          jwt
        );

        if (!metadataResult.success) {
          throw new Error('Failed to update session metadata');
        }
      }

      // Save content if changed
      if (editor.isContentDirty) {
        const contentResult = await clientUpdateSessionContent(
          contentUri,
          projectId,
          session.storageKey,
          editor.sessionData,
          jwt
        );

        if (!contentResult.success) {
          throw new Error(contentResult.error);
        }
      }

      // Navigate back to session view
      navigate(`/project/${projectId}/session/${session.sessionId}`);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      setSaveError(errorMessage);
    } finally {
      setIsSaving(false);
    }
  }, [editor, session, projectId, navigate, jwt, apiUri, contentUri]);

  /**
   * Handle delete action
   */
  const handleDelete = useCallback(async () => {
    if (
      !confirm(
        'Are you sure you want to delete this coding session? This action cannot be undone.'
      )
    ) {
      return;
    }

    setIsSaving(true);
    setSaveError(undefined);

    try {
      const result = await clientDeleteCodingSession(
        apiUri,
        contentUri,
        session.codingSessionPkId,
        projectId,
        session.storageKey,
        jwt
      );

      if (!result.success) {
        throw new Error(result.error);
      }

      // Navigate back to project view
      navigate(`/project/${projectId}`);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      setSaveError(errorMessage);
    } finally {
      setIsSaving(false);
    }
  }, [session, projectId, navigate, jwt, apiUri, contentUri]);

  /**
   * Navigate to a sensitive match
   */
  const handleNavigateToMatch = useCallback((match: SensitiveMatch) => {
    const messageElement = messageRefs.current.get(match.messageUuid);
    if (messageElement) {
      messageElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
    }
  }, []);

  /**
   * Handle message deletion
   */
  const handleDeleteMessage = useCallback(
    (messageUuid: string) => {
      if (confirm('Are you sure you want to delete this message?')) {
        editor.deleteMessage(messageUuid);
      }
    },
    [editor]
  );

  /**
   * Handle content block update
   */
  const handleUpdateContentBlock = useCallback(
    (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => {
      editor.updateContentBlock(messageUuid, contentIndex, newContent);
    },
    [editor]
  );

  /**
   * Handle content block deletion
   */
  const handleDeleteContentBlock = useCallback(
    (messageUuid: string, contentIndex: number) => {
      if (confirm('Are you sure you want to delete this content block?')) {
        editor.deleteContentBlock(messageUuid, contentIndex);
      }
    },
    [editor]
  );

  return (
    <div className="h-screen flex flex-col bg-background">
      <EditorToolbar
        projectId={projectId}
        sessionId={session.sessionId}
        isDirty={editor.isDirty}
        canUndo={editor.canUndo}
        isSaving={isSaving}
        onSave={handleSave}
        onUndo={editor.undo}
        onDelete={handleDelete}
      />

      {saveError && (
        <div className="p-4 bg-destructive/10 text-destructive border-b">Error: {saveError}</div>
      )}

      <ScrollArea className="flex-1">
        <div className="p-4 max-w-4xl mx-auto">
          <SessionMetadataEditor
            description={editor.description}
            published={editor.published}
            onDescriptionChange={editor.setDescription}
            onPublishedChange={editor.setPublished}
          />

          <SensitiveDataSearch
            matches={sensitiveSearch.matches}
            activePatterns={sensitiveSearch.activePatterns}
            customPatterns={sensitiveSearch.customPatterns}
            builtInPatterns={sensitiveSearch.builtInPatterns}
            onTogglePattern={sensitiveSearch.togglePattern}
            onAddCustomPattern={sensitiveSearch.addCustomPattern}
            onRemoveCustomPattern={sensitiveSearch.removeCustomPattern}
            onNavigateToMatch={handleNavigateToMatch}
          />

          <h3 className="text-lg font-semibold mb-4">
            Messages ({editor.sessionData.messages.length})
          </h3>

          <div className="space-y-4">
            {editor.sessionData.messages.map((message: CwcSessionMessage, index: number) => (
              <div
                key={message.uuid}
                ref={(el) => {
                  if (el) {
                    messageRefs.current.set(message.uuid, el);
                  } else {
                    messageRefs.current.delete(message.uuid);
                  }
                }}
              >
                <MessageEditor
                  message={message}
                  messageIndex={index}
                  projectOwnerUsername={projectOwnerUsername}
                  highlightedContentIndices={highlightMap.get(message.uuid)}
                  onDeleteMessage={() => handleDeleteMessage(message.uuid)}
                  onUpdateContentBlock={(contentIndex, newContent) =>
                    handleUpdateContentBlock(message.uuid, contentIndex, newContent)
                  }
                  onDeleteContentBlock={(contentIndex) =>
                    handleDeleteContentBlock(message.uuid, contentIndex)
                  }
                />
              </div>
            ))}
          </div>
        </div>
      </ScrollArea>
    </div>
  );
}

Version 2 (latest)

import type { ReactNode } from 'react';
import { useState, useCallback, useRef } from 'react';
import { useNavigate, useParams } from 'react-router';
import type { CwcSessionMessage, CwcSessionContent } from 'cwc-types';
import { ScrollArea } from '@/components/ui/scroll-area';
import { useConfig, useAuth } from '@/hooks';
import {
  clientUpdateCodingSession,
  clientUpdateSessionContent,
  clientDeleteCodingSession,
} from '@/clientApi';
import { EditorToolbar } from './components/EditorToolbar';
import { SessionMetadataEditor } from './components/SessionMetadataEditor';
import { MessageEditor, buildHighlightMap } from './components/MessageEditor';
import { SensitiveDataSearch } from './components/SensitiveDataSearch';
import { useSessionEditor } from './hooks/useSessionEditor';
import { useSensitiveSearch, type SensitiveMatch } from './hooks/useSensitiveSearch';
import { useCodingSessionEditorData } from './hooks/useCodingSessionEditorData';

/**
 * Loading spinner component
 */
function LoadingSpinner(): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
        <p className="text-muted-foreground">Loading session editor...</p>
      </div>
    </div>
  );
}

/**
 * Error display component
 */
function ErrorDisplay({ error, onBack }: { error: string; onBack: () => void }): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center max-w-md">
        <div className="text-destructive text-4xl mb-4">⚠</div>
        <h1 className="text-xl font-semibold mb-2">Error Loading Session</h1>
        <p className="text-muted-foreground mb-4">{error}</p>
        <button
          onClick={onBack}
          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
        >
          Go Back
        </button>
      </div>
    </div>
  );
}

/**
 * Unauthorized display component
 */
function UnauthorizedDisplay({
  message,
  onBack,
}: {
  message: string;
  onBack: () => void;
}): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center max-w-md">
        <div className="text-warning text-4xl mb-4">🔒</div>
        <h1 className="text-xl font-semibold mb-2">Access Denied</h1>
        <p className="text-muted-foreground mb-4">{message}</p>
        <button
          onClick={onBack}
          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
        >
          Go Back
        </button>
      </div>
    </div>
  );
}

/**
 * Coding session editor page (client-side rendered)
 *
 * Allows project owners to edit session metadata, message content,
 * and search for sensitive data.
 *
 * Data is fetched client-side after component mount to ensure
 * proper authentication context is available.
 */
export default function CodingSessionEditor(): ReactNode {
  const { codingSessionPkId } = useParams();
  const navigate = useNavigate();
  const config = useConfig();
  const { login } = useAuth();

  // Load data client-side
  const editorState = useCodingSessionEditorData(codingSessionPkId);

  // Handle back navigation (before data is loaded)
  const handleBack = useCallback(() => {
    navigate('/');
  }, [navigate]);

  // Show loading state
  if (editorState.status === 'loading') {
    return <LoadingSpinner />;
  }

  // Show error state
  if (editorState.status === 'error') {
    return <ErrorDisplay error={editorState.error} onBack={handleBack} />;
  }

  // Show unauthorized state
  if (editorState.status === 'unauthorized') {
    return <UnauthorizedDisplay message={editorState.message} onBack={handleBack} />;
  }

  // Data is ready - render the editor
  const { data } = editorState;

  return (
    <CodingSessionEditorContent
      codingSessionPkId={data.session.codingSessionPkId}
      projectId={data.projectId}
      session={data.session}
      initialSessionData={data.sessionData}
      projectOwnerUsername={data.projectOwnerUsername}
      jwt={login?.authToken ?? ''}
      apiUri={config.apiUriExternal}
      contentUri={config.contentUriExternal}
    />
  );
}

/**
 * Editor content component (extracted for cleaner code)
 */
function CodingSessionEditorContent({
  codingSessionPkId,
  projectId,
  session,
  initialSessionData,
  projectOwnerUsername,
  jwt,
  apiUri,
  contentUri,
}: {
  codingSessionPkId: number;
  projectId: string;
  session: {
    codingSessionPkId: number;
    sessionId: string;
    storageKey: string;
  };
  initialSessionData: Parameters<typeof useSessionEditor>[1];
  projectOwnerUsername?: string;
  jwt: string;
  apiUri: string;
  contentUri: string;
}): ReactNode {
  const navigate = useNavigate();

  // Editor state
  const editor = useSessionEditor(
    session as Parameters<typeof useSessionEditor>[0],
    initialSessionData
  );

  // Sensitive data search
  const sensitiveSearch = useSensitiveSearch(editor.sessionData);

  // Saving state
  const [isSaving, setIsSaving] = useState(false);
  const [saveError, setSaveError] = useState<string | undefined>();

  // Message refs for scroll-to navigation
  const messageRefs = useRef<Map<string, HTMLDivElement>>(new Map());

  // Build highlight map from sensitive matches
  const highlightMap = buildHighlightMap(sensitiveSearch.matches);

  /**
   * Handle save action
   */
  const handleSave = useCallback(async () => {
    setIsSaving(true);
    setSaveError(undefined);

    try {
      // Save metadata if changed
      if (editor.isMetadataDirty) {
        const metadataResult = await clientUpdateCodingSession(
          apiUri,
          session.codingSessionPkId,
          {
            description: editor.description,
            published: editor.published,
          },
          jwt
        );

        if (!metadataResult.success) {
          throw new Error('Failed to update session metadata');
        }
      }

      // Save content if changed
      if (editor.isContentDirty) {
        const contentResult = await clientUpdateSessionContent(
          contentUri,
          projectId,
          session.storageKey,
          editor.sessionData,
          jwt
        );

        if (!contentResult.success) {
          throw new Error(contentResult.error);
        }
      }

      // Mark as saved (user stays on editor page)
      editor.markSaved();
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      setSaveError(errorMessage);
    } finally {
      setIsSaving(false);
    }
  }, [editor, session, projectId, jwt, apiUri, contentUri]);

  /**
   * Handle delete action
   */
  const handleDelete = useCallback(async () => {
    if (
      !confirm(
        'Are you sure you want to delete this coding session? This action cannot be undone.'
      )
    ) {
      return;
    }

    setIsSaving(true);
    setSaveError(undefined);

    try {
      const result = await clientDeleteCodingSession(
        apiUri,
        contentUri,
        session.codingSessionPkId,
        projectId,
        session.storageKey,
        jwt
      );

      if (!result.success) {
        throw new Error(result.error);
      }

      // Navigate back to project view
      navigate(`/project/${projectId}`);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      setSaveError(errorMessage);
    } finally {
      setIsSaving(false);
    }
  }, [session, projectId, navigate, jwt, apiUri, contentUri]);

  /**
   * Navigate to a sensitive match
   */
  const handleNavigateToMatch = useCallback((match: SensitiveMatch) => {
    const messageElement = messageRefs.current.get(match.messageUuid);
    if (messageElement) {
      messageElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
    }
  }, []);

  /**
   * Handle message deletion
   */
  const handleDeleteMessage = useCallback(
    (messageUuid: string) => {
      if (confirm('Are you sure you want to delete this message?')) {
        editor.deleteMessage(messageUuid);
      }
    },
    [editor]
  );

  /**
   * Handle content block update
   */
  const handleUpdateContentBlock = useCallback(
    (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => {
      editor.updateContentBlock(messageUuid, contentIndex, newContent);
    },
    [editor]
  );

  /**
   * Handle content block deletion
   */
  const handleDeleteContentBlock = useCallback(
    (messageUuid: string, contentIndex: number) => {
      if (confirm('Are you sure you want to delete this content block?')) {
        editor.deleteContentBlock(messageUuid, contentIndex);
      }
    },
    [editor]
  );

  return (
    <div className="h-screen flex flex-col bg-background">
      <EditorToolbar
        codingSessionPkId={codingSessionPkId}
        isDirty={editor.isDirty}
        canUndo={editor.canUndo}
        isSaving={isSaving}
        onSave={handleSave}
        onUndo={editor.undo}
        onDelete={handleDelete}
      />

      {saveError && (
        <div className="p-4 bg-destructive/10 text-destructive border-b">Error: {saveError}</div>
      )}

      <ScrollArea className="flex-1">
        <div className="p-4 max-w-4xl mx-auto">
          <SessionMetadataEditor
            description={editor.description}
            published={editor.published}
            onDescriptionChange={editor.setDescription}
            onPublishedChange={editor.setPublished}
          />

          <SensitiveDataSearch
            matches={sensitiveSearch.matches}
            activePatterns={sensitiveSearch.activePatterns}
            customPatterns={sensitiveSearch.customPatterns}
            builtInPatterns={sensitiveSearch.builtInPatterns}
            onTogglePattern={sensitiveSearch.togglePattern}
            onAddCustomPattern={sensitiveSearch.addCustomPattern}
            onRemoveCustomPattern={sensitiveSearch.removeCustomPattern}
            onNavigateToMatch={handleNavigateToMatch}
          />

          <h3 className="text-lg font-semibold mb-4">
            Messages ({editor.sessionData.messages.length})
          </h3>

          <div className="space-y-4">
            {editor.sessionData.messages.map((message: CwcSessionMessage, index: number) => (
              <div
                key={message.uuid}
                ref={(el) => {
                  if (el) {
                    messageRefs.current.set(message.uuid, el);
                  } else {
                    messageRefs.current.delete(message.uuid);
                  }
                }}
              >
                <MessageEditor
                  message={message}
                  messageIndex={index}
                  projectOwnerUsername={projectOwnerUsername}
                  highlightedContentIndices={highlightMap.get(message.uuid)}
                  onDeleteMessage={() => handleDeleteMessage(message.uuid)}
                  onUpdateContentBlock={(contentIndex, newContent) =>
                    handleUpdateContentBlock(message.uuid, contentIndex, newContent)
                  }
                  onDeleteContentBlock={(contentIndex) =>
                    handleDeleteContentBlock(message.uuid, contentIndex)
                  }
                />
              </div>
            ))}
          </div>
        </div>
      </ScrollArea>
    </div>
  );
}

packages/cwc-website/src/views/client/CodingSessionEditor/components/EditorToolbar.tsx

import type { ReactNode } from 'react';
import { Link } from 'react-router';
import { Save, X, Undo2, Trash2 } from 'lucide-react';
import { Button } from '@/components/ui/button';

type EditorToolbarProps = {
  codingSessionPkId: number;
  isDirty: boolean;
  canUndo: boolean;
  isSaving: boolean;
  onSave: () => void;
  onUndo: () => void;
  onDelete: () => void;
};

/**
 * Editor toolbar with save, cancel, undo, and delete actions
 */
export function EditorToolbar({
  codingSessionPkId,
  isDirty,
  canUndo,
  isSaving,
  onSave,
  onUndo,
  onDelete,
}: EditorToolbarProps): ReactNode {
  const cancelUrl = `/session/${codingSessionPkId}`;

  return (
    <div className="flex items-center gap-2 p-4 border-b bg-background sticky top-0 z-10">
      <Button onClick={onSave} disabled={!isDirty || isSaving} size="sm">
        <Save className="h-4 w-4" />
        {isSaving ? 'Saving...' : 'Save'}
      </Button>

      <Button variant="outline" size="sm" asChild>
        <Link to={cancelUrl}>
          <X className="h-4 w-4" />
          Cancel
        </Link>
      </Button>

      <Button variant="outline" size="sm" onClick={onUndo} disabled={!canUndo}>
        <Undo2 className="h-4 w-4" />
        Undo
      </Button>

      <div className="flex-1" />

      <Button variant="destructive" size="sm" onClick={onDelete}>
        <Trash2 className="h-4 w-4" />
        Delete Session
      </Button>
    </div>
  );
}

packages/cwc-website/src/views/client/CodingSessionEditor/hooks/useCodingSessionEditorData.ts

import { useState, useEffect } from 'react';
import type { CwcCodingSession, CwcSessionData } from 'cwc-types';
import { useConfig, useAuth } from '@/hooks';
import {
  clientGetCodingSession,
  clientGetProjectByPkId,
  clientGetSessionData,
  clientGetUser,
} from '@/clientApi';

/**
 * Editor data loaded from API
 */
export type EditorData = {
  projectId: string;
  session: CwcCodingSession;
  sessionData: CwcSessionData;
  projectOwnerUsername?: string;
};

/**
 * State for the editor data loading
 */
export type EditorDataState =
  | { status: 'loading' }
  | { status: 'error'; error: string }
  | { status: 'unauthorized'; message: string }
  | { status: 'ready'; data: EditorData };

/**
 * Hook to load coding session editor data client-side
 *
 * Fetches session metadata and content after component mount using
 * external API URLs and client-side gzip decompression.
 *
 * @param codingSessionPkIdParam - The codingSessionPkId from URL params (string)
 */
export function useCodingSessionEditorData(
  codingSessionPkIdParam: string | undefined
): EditorDataState {
  const config = useConfig();
  const { isAuthenticated, login } = useAuth();
  const [state, setState] = useState<EditorDataState>({ status: 'loading' });

  useEffect(() => {
    // Validate params
    if (!codingSessionPkIdParam) {
      setState({ status: 'error', error: 'codingSessionPkId is required' });
      return;
    }

    const codingSessionPkId = parseInt(codingSessionPkIdParam, 10);
    if (isNaN(codingSessionPkId)) {
      setState({ status: 'error', error: 'Invalid codingSessionPkId' });
      return;
    }

    // Check authentication
    if (!isAuthenticated || !login) {
      setState({ status: 'unauthorized', message: 'You must be logged in to edit sessions' });
      return;
    }

    // Reset to loading state when params change
    setState({ status: 'loading' });

    // Fetch data
    const loadData = async (): Promise<void> => {
      try {
        // Fetch session metadata
        const sessionResult = await clientGetCodingSession(
          config.apiUriExternal,
          codingSessionPkId
        );

        if (!sessionResult.success) {
          setState({ status: 'error', error: 'Coding session not found' });
          return;
        }

        const session = sessionResult.data;

        // Fetch project to get projectId for ownership check and storage
        const projectResult = await clientGetProjectByPkId(
          config.apiUriExternal,
          session.projectPkId
        );

        if (!projectResult.success) {
          setState({ status: 'error', error: 'Project not found' });
          return;
        }

        const project = projectResult.data;
        const projectId = project.projectId;

        // Verify user owns the project
        const userOwnsProject = login.ownedProjects.includes(projectId);
        if (!userOwnsProject) {
          setState({
            status: 'unauthorized',
            message: 'You do not have permission to edit this session',
          });
          return;
        }

        // Check storage key exists
        if (!session.storageKey) {
          setState({ status: 'error', error: 'Session content not available' });
          return;
        }

        // Fetch session data (content)
        const sessionData = await clientGetSessionData(
          config.contentUriExternal,
          projectId,
          session.storageKey
        );

        if (!sessionData) {
          setState({ status: 'error', error: 'Failed to load session content' });
          return;
        }

        // Fetch project owner username
        const userResult = await clientGetUser(config.apiUriExternal, session.userPkId);
        const projectOwnerUsername = userResult.success ? userResult.data.username : undefined;

        // Success
        setState({
          status: 'ready',
          data: {
            projectId,
            session,
            sessionData,
            projectOwnerUsername,
          },
        });
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
        setState({ status: 'error', error: errorMessage });
      }
    };

    loadData();
  }, [codingSessionPkIdParam, config.apiUriExternal, config.contentUriExternal, isAuthenticated, login]);

  return state;
}

packages/cwc-website/src/views/client/CodingSessionEditor/hooks/useSessionEditor.ts

2 versions

Version 1

import { useState, useCallback, useMemo, useRef } from 'react';
import type {
  CwcCodingSession,
  CwcSessionData,
  CwcSessionMessage,
  CwcSessionContent,
} from 'cwc-types';
import { useUndoStack } from './useUndoStack';

export type SessionEditorState = {
  // Session metadata
  description: string;
  published: boolean;
  // Session data (messages)
  sessionData: CwcSessionData;
  // Dirty tracking
  isDirty: boolean;
  isMetadataDirty: boolean;
  isContentDirty: boolean;
};

export type SessionEditorActions = {
  // Metadata actions
  setDescription: (description: string) => void;
  setPublished: (published: boolean) => void;
  // Content actions
  deleteMessage: (messageUuid: string) => void;
  updateContentBlock: (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => void;
  deleteContentBlock: (messageUuid: string, contentIndex: number) => void;
  // Undo
  undo: () => void;
  canUndo: boolean;
  // Reset
  reset: () => void;
};

/**
 * Hook for managing session editor state
 *
 * Provides state and actions for editing session metadata and content.
 * Tracks dirty state and provides undo functionality.
 */
export function useSessionEditor(
  initialSession: CwcCodingSession,
  initialSessionData: CwcSessionData
): SessionEditorState & SessionEditorActions {
  // Metadata state
  const [description, setDescriptionState] = useState(initialSession.description);
  const [published, setPublishedState] = useState(initialSession.published);

  // Content state (deep copy to allow mutations)
  const [sessionData, setSessionData] = useState<CwcSessionData>(() =>
    JSON.parse(JSON.stringify(initialSessionData))
  );

  // Undo stack
  const { canUndo, pushUndo, popUndo, clearUndo } = useUndoStack();

  // Track dirty state
  const isMetadataDirty = useMemo(() => {
    return description !== initialSession.description || published !== initialSession.published;
  }, [description, published, initialSession.description, initialSession.published]);

  const isContentDirty = useMemo(() => {
    return JSON.stringify(sessionData) !== JSON.stringify(initialSessionData);
  }, [sessionData, initialSessionData]);

  const isDirty = isMetadataDirty || isContentDirty;

  // Metadata actions
  const setDescription = useCallback((newDescription: string) => {
    setDescriptionState(newDescription);
  }, []);

  const setPublished = useCallback((newPublished: boolean) => {
    setPublishedState(newPublished);
  }, []);

  // Content actions
  const deleteMessage = useCallback(
    (messageUuid: string) => {
      setSessionData((prev) => {
        // Push current state to undo stack
        pushUndo(prev);

        // Filter out the message
        const newMessages = prev.messages.filter(
          (msg: CwcSessionMessage) => msg.uuid !== messageUuid
        );

        return {
          ...prev,
          messages: newMessages,
        };
      });
    },
    [pushUndo]
  );

  const updateContentBlock = useCallback(
    (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => {
      setSessionData((prev) => {
        // Push current state to undo stack
        pushUndo(prev);

        const newMessages = prev.messages.map((msg: CwcSessionMessage) => {
          if (msg.uuid !== messageUuid) return msg;

          const newContentArray = [...msg.content];
          newContentArray[contentIndex] = newContent;

          return {
            ...msg,
            content: newContentArray,
          };
        });

        return {
          ...prev,
          messages: newMessages,
        };
      });
    },
    [pushUndo]
  );

  const deleteContentBlock = useCallback(
    (messageUuid: string, contentIndex: number) => {
      setSessionData((prev) => {
        // Push current state to undo stack
        pushUndo(prev);

        const newMessages = prev.messages.map((msg: CwcSessionMessage) => {
          if (msg.uuid !== messageUuid) return msg;

          const newContentArray = msg.content.filter((_, index) => index !== contentIndex);

          return {
            ...msg,
            content: newContentArray,
          };
        });

        return {
          ...prev,
          messages: newMessages,
        };
      });
    },
    [pushUndo]
  );

  // Undo action
  const undo = useCallback(() => {
    const previousState = popUndo();
    if (previousState) {
      setSessionData(previousState);
    }
  }, [popUndo]);

  // Reset to initial state
  const reset = useCallback(() => {
    setDescriptionState(initialSession.description);
    setPublishedState(initialSession.published);
    setSessionData(JSON.parse(JSON.stringify(initialSessionData)));
    clearUndo();
  }, [initialSession, initialSessionData, clearUndo]);

  return {
    // State
    description,
    published,
    sessionData,
    isDirty,
    isMetadataDirty,
    isContentDirty,
    // Actions
    setDescription,
    setPublished,
    deleteMessage,
    updateContentBlock,
    deleteContentBlock,
    undo,
    canUndo,
    reset,
  };
}

Version 2 (latest)

import { useState, useCallback, useMemo, useRef } from 'react';
import type {
  CwcCodingSession,
  CwcSessionData,
  CwcSessionMessage,
  CwcSessionContent,
} from 'cwc-types';
import { useUndoStack } from './useUndoStack';

export type SessionEditorState = {
  // Session metadata
  description: string;
  published: boolean;
  // Session data (messages)
  sessionData: CwcSessionData;
  // Dirty tracking
  isDirty: boolean;
  isMetadataDirty: boolean;
  isContentDirty: boolean;
};

export type SessionEditorActions = {
  // Metadata actions
  setDescription: (description: string) => void;
  setPublished: (published: boolean) => void;
  // Content actions
  deleteMessage: (messageUuid: string) => void;
  updateContentBlock: (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => void;
  deleteContentBlock: (messageUuid: string, contentIndex: number) => void;
  // Undo
  undo: () => void;
  canUndo: boolean;
  // Reset
  reset: () => void;
  // Save
  markSaved: () => void;
};

/**
 * Hook for managing session editor state
 *
 * Provides state and actions for editing session metadata and content.
 * Tracks dirty state and provides undo functionality.
 */
export function useSessionEditor(
  initialSession: CwcCodingSession,
  initialSessionData: CwcSessionData
): SessionEditorState & SessionEditorActions {
  // Metadata state
  const [description, setDescriptionState] = useState(initialSession.description);
  const [published, setPublishedState] = useState(initialSession.published);

  // Content state (deep copy to allow mutations)
  const [sessionData, setSessionData] = useState<CwcSessionData>(() =>
    JSON.parse(JSON.stringify(initialSessionData))
  );

  // Track the "last saved" state for dirty comparison
  // These refs update when markSaved() is called
  const savedDescriptionRef = useRef(initialSession.description);
  const savedPublishedRef = useRef(initialSession.published);
  const savedSessionDataRef = useRef<string>(JSON.stringify(initialSessionData));
  // Force re-render after markSaved
  const [savedVersion, setSavedVersion] = useState(0);

  // Undo stack
  const { canUndo, pushUndo, popUndo, clearUndo } = useUndoStack();

  // Track dirty state (compare against last saved state)
  const isMetadataDirty = useMemo(() => {
    // savedVersion dependency ensures re-computation after markSaved
    void savedVersion;
    return description !== savedDescriptionRef.current || published !== savedPublishedRef.current;
  }, [description, published, savedVersion]);

  const isContentDirty = useMemo(() => {
    // savedVersion dependency ensures re-computation after markSaved
    void savedVersion;
    return JSON.stringify(sessionData) !== savedSessionDataRef.current;
  }, [sessionData, savedVersion]);

  const isDirty = isMetadataDirty || isContentDirty;

  // Metadata actions
  const setDescription = useCallback((newDescription: string) => {
    setDescriptionState(newDescription);
  }, []);

  const setPublished = useCallback((newPublished: boolean) => {
    setPublishedState(newPublished);
  }, []);

  // Content actions
  const deleteMessage = useCallback(
    (messageUuid: string) => {
      setSessionData((prev) => {
        // Push current state to undo stack
        pushUndo(prev);

        // Filter out the message
        const newMessages = prev.messages.filter(
          (msg: CwcSessionMessage) => msg.uuid !== messageUuid
        );

        return {
          ...prev,
          messages: newMessages,
        };
      });
    },
    [pushUndo]
  );

  const updateContentBlock = useCallback(
    (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => {
      setSessionData((prev) => {
        // Push current state to undo stack
        pushUndo(prev);

        const newMessages = prev.messages.map((msg: CwcSessionMessage) => {
          if (msg.uuid !== messageUuid) return msg;

          const newContentArray = [...msg.content];
          newContentArray[contentIndex] = newContent;

          return {
            ...msg,
            content: newContentArray,
          };
        });

        return {
          ...prev,
          messages: newMessages,
        };
      });
    },
    [pushUndo]
  );

  const deleteContentBlock = useCallback(
    (messageUuid: string, contentIndex: number) => {
      setSessionData((prev) => {
        // Push current state to undo stack
        pushUndo(prev);

        const newMessages = prev.messages.map((msg: CwcSessionMessage) => {
          if (msg.uuid !== messageUuid) return msg;

          const newContentArray = msg.content.filter((_, index) => index !== contentIndex);

          return {
            ...msg,
            content: newContentArray,
          };
        });

        return {
          ...prev,
          messages: newMessages,
        };
      });
    },
    [pushUndo]
  );

  // Undo action
  const undo = useCallback(() => {
    const previousState = popUndo();
    if (previousState) {
      setSessionData(previousState);
    }
  }, [popUndo]);

  // Reset to initial state
  const reset = useCallback(() => {
    setDescriptionState(initialSession.description);
    setPublishedState(initialSession.published);
    setSessionData(JSON.parse(JSON.stringify(initialSessionData)));
    clearUndo();
  }, [initialSession, initialSessionData, clearUndo]);

  // Mark current state as saved (updates the comparison baseline)
  const markSaved = useCallback(() => {
    savedDescriptionRef.current = description;
    savedPublishedRef.current = published;
    savedSessionDataRef.current = JSON.stringify(sessionData);
    // Increment version to trigger re-computation of dirty flags
    setSavedVersion((v) => v + 1);
    // Clear undo stack since we've saved
    clearUndo();
  }, [description, published, sessionData, clearUndo]);

  return {
    // State
    description,
    published,
    sessionData,
    isDirty,
    isMetadataDirty,
    isContentDirty,
    // Actions
    setDescription,
    setPublished,
    deleteMessage,
    updateContentBlock,
    deleteContentBlock,
    undo,
    canUndo,
    reset,
    markSaved,
  };
}

packages/cwc-website/src/views/CodingSessionEditor/CodingSessionEditor.tsx

import type { ReactNode } from 'react';
import { useState, useCallback, useRef } from 'react';
import { useNavigate, useParams } from 'react-router';
import type { CwcSessionMessage, CwcSessionContent } from 'cwc-types';
import { ScrollArea } from '@/components/ui/scroll-area';
import { useConfig, useAuth } from '@/hooks';
import {
  clientUpdateCodingSession,
  clientUpdateSessionContent,
  clientDeleteCodingSession,
} from '@/clientApi';
import { EditorToolbar } from './components/EditorToolbar';
import { SessionMetadataEditor } from './components/SessionMetadataEditor';
import { MessageEditor, buildHighlightMap } from './components/MessageEditor';
import { SensitiveDataSearch } from './components/SensitiveDataSearch';
import { useSessionEditor } from './hooks/useSessionEditor';
import { useSensitiveSearch, type SensitiveMatch } from './hooks/useSensitiveSearch';
import { useCodingSessionEditorData } from './hooks/useCodingSessionEditorData';

/**
 * Loading spinner component
 */
function LoadingSpinner(): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto mb-4" />
        <p className="text-muted-foreground">Loading session editor...</p>
      </div>
    </div>
  );
}

/**
 * Error display component
 */
function ErrorDisplay({ error, onBack }: { error: string; onBack: () => void }): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center max-w-md">
        <div className="text-destructive text-4xl mb-4">⚠</div>
        <h1 className="text-xl font-semibold mb-2">Error Loading Session</h1>
        <p className="text-muted-foreground mb-4">{error}</p>
        <button
          onClick={onBack}
          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
        >
          Go Back
        </button>
      </div>
    </div>
  );
}

/**
 * Unauthorized display component
 */
function UnauthorizedDisplay({
  message,
  onBack,
}: {
  message: string;
  onBack: () => void;
}): ReactNode {
  return (
    <div className="h-screen flex items-center justify-center bg-background">
      <div className="text-center max-w-md">
        <div className="text-warning text-4xl mb-4">🔒</div>
        <h1 className="text-xl font-semibold mb-2">Access Denied</h1>
        <p className="text-muted-foreground mb-4">{message}</p>
        <button
          onClick={onBack}
          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
        >
          Go Back
        </button>
      </div>
    </div>
  );
}

/**
 * Coding session editor page (client-side rendered)
 *
 * Allows project owners to edit session metadata, message content,
 * and search for sensitive data.
 *
 * Data is fetched client-side after component mount to ensure
 * proper authentication context is available.
 */
export default function CodingSessionEditor(): ReactNode {
  const { projectId, sessionId } = useParams();
  const navigate = useNavigate();
  const config = useConfig();
  const { login } = useAuth();

  // Load data client-side
  const editorState = useCodingSessionEditorData(projectId, sessionId);

  // Handle back navigation
  const handleBack = useCallback(() => {
    if (projectId) {
      navigate(`/project/${projectId}`);
    } else {
      navigate('/');
    }
  }, [projectId, navigate]);

  // Show loading state
  if (editorState.status === 'loading') {
    return <LoadingSpinner />;
  }

  // Show error state
  if (editorState.status === 'error') {
    return <ErrorDisplay error={editorState.error} onBack={handleBack} />;
  }

  // Show unauthorized state
  if (editorState.status === 'unauthorized') {
    return <UnauthorizedDisplay message={editorState.message} onBack={handleBack} />;
  }

  // Data is ready - render the editor
  const { data } = editorState;

  return (
    <CodingSessionEditorContent
      projectId={data.projectId}
      session={data.session}
      initialSessionData={data.sessionData}
      projectOwnerUsername={data.projectOwnerUsername}
      jwt={login?.authToken ?? ''}
      apiUri={config.apiUriExternal}
      contentUri={config.contentUriExternal}
    />
  );
}

/**
 * Editor content component (extracted for cleaner code)
 */
function CodingSessionEditorContent({
  projectId,
  session,
  initialSessionData,
  projectOwnerUsername,
  jwt,
  apiUri,
  contentUri,
}: {
  projectId: string;
  session: {
    codingSessionPkId: number;
    sessionId: string;
    storageKey: string;
  };
  initialSessionData: Parameters<typeof useSessionEditor>[1];
  projectOwnerUsername?: string;
  jwt: string;
  apiUri: string;
  contentUri: string;
}): ReactNode {
  const navigate = useNavigate();

  // Editor state
  const editor = useSessionEditor(
    session as Parameters<typeof useSessionEditor>[0],
    initialSessionData
  );

  // Sensitive data search
  const sensitiveSearch = useSensitiveSearch(editor.sessionData);

  // Saving state
  const [isSaving, setIsSaving] = useState(false);
  const [saveError, setSaveError] = useState<string | undefined>();

  // Message refs for scroll-to navigation
  const messageRefs = useRef<Map<string, HTMLDivElement>>(new Map());

  // Build highlight map from sensitive matches
  const highlightMap = buildHighlightMap(sensitiveSearch.matches);

  /**
   * Handle save action
   */
  const handleSave = useCallback(async () => {
    setIsSaving(true);
    setSaveError(undefined);

    try {
      // Save metadata if changed
      if (editor.isMetadataDirty) {
        const metadataResult = await clientUpdateCodingSession(
          apiUri,
          session.codingSessionPkId,
          {
            description: editor.description,
            published: editor.published,
          },
          jwt
        );

        if (!metadataResult.success) {
          throw new Error('Failed to update session metadata');
        }
      }

      // Save content if changed
      if (editor.isContentDirty) {
        const contentResult = await clientUpdateSessionContent(
          contentUri,
          projectId,
          session.storageKey,
          editor.sessionData,
          jwt
        );

        if (!contentResult.success) {
          throw new Error(contentResult.error);
        }
      }

      // Navigate back to session view
      navigate(`/project/${projectId}/session/${session.sessionId}`);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      setSaveError(errorMessage);
    } finally {
      setIsSaving(false);
    }
  }, [editor, session, projectId, navigate, jwt, apiUri, contentUri]);

  /**
   * Handle delete action
   */
  const handleDelete = useCallback(async () => {
    if (
      !confirm(
        'Are you sure you want to delete this coding session? This action cannot be undone.'
      )
    ) {
      return;
    }

    setIsSaving(true);
    setSaveError(undefined);

    try {
      const result = await clientDeleteCodingSession(
        apiUri,
        contentUri,
        session.codingSessionPkId,
        projectId,
        session.storageKey,
        jwt
      );

      if (!result.success) {
        throw new Error(result.error);
      }

      // Navigate back to project view
      navigate(`/project/${projectId}`);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      setSaveError(errorMessage);
    } finally {
      setIsSaving(false);
    }
  }, [session, projectId, navigate, jwt, apiUri, contentUri]);

  /**
   * Navigate to a sensitive match
   */
  const handleNavigateToMatch = useCallback((match: SensitiveMatch) => {
    const messageElement = messageRefs.current.get(match.messageUuid);
    if (messageElement) {
      messageElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
    }
  }, []);

  /**
   * Handle message deletion
   */
  const handleDeleteMessage = useCallback(
    (messageUuid: string) => {
      if (confirm('Are you sure you want to delete this message?')) {
        editor.deleteMessage(messageUuid);
      }
    },
    [editor]
  );

  /**
   * Handle content block update
   */
  const handleUpdateContentBlock = useCallback(
    (messageUuid: string, contentIndex: number, newContent: CwcSessionContent) => {
      editor.updateContentBlock(messageUuid, contentIndex, newContent);
    },
    [editor]
  );

  /**
   * Handle content block deletion
   */
  const handleDeleteContentBlock = useCallback(
    (messageUuid: string, contentIndex: number) => {
      if (confirm('Are you sure you want to delete this content block?')) {
        editor.deleteContentBlock(messageUuid, contentIndex);
      }
    },
    [editor]
  );

  return (
    <div className="h-screen flex flex-col bg-background">
      <EditorToolbar
        projectId={projectId}
        sessionId={session.sessionId}
        isDirty={editor.isDirty}
        canUndo={editor.canUndo}
        isSaving={isSaving}
        onSave={handleSave}
        onUndo={editor.undo}
        onDelete={handleDelete}
      />

      {saveError && (
        <div className="p-4 bg-destructive/10 text-destructive border-b">Error: {saveError}</div>
      )}

      <ScrollArea className="flex-1">
        <div className="p-4 max-w-4xl mx-auto">
          <SessionMetadataEditor
            description={editor.description}
            published={editor.published}
            onDescriptionChange={editor.setDescription}
            onPublishedChange={editor.setPublished}
          />

          <SensitiveDataSearch
            matches={sensitiveSearch.matches}
            activePatterns={sensitiveSearch.activePatterns}
            customPatterns={sensitiveSearch.customPatterns}
            builtInPatterns={sensitiveSearch.builtInPatterns}
            onTogglePattern={sensitiveSearch.togglePattern}
            onAddCustomPattern={sensitiveSearch.addCustomPattern}
            onRemoveCustomPattern={sensitiveSearch.removeCustomPattern}
            onNavigateToMatch={handleNavigateToMatch}
          />

          <h3 className="text-lg font-semibold mb-4">
            Messages ({editor.sessionData.messages.length})
          </h3>

          <div className="space-y-4">
            {editor.sessionData.messages.map((message: CwcSessionMessage, index: number) => (
              <div
                key={message.uuid}
                ref={(el) => {
                  if (el) {
                    messageRefs.current.set(message.uuid, el);
                  } else {
                    messageRefs.current.delete(message.uuid);
                  }
                }}
              >
                <MessageEditor
                  message={message}
                  messageIndex={index}
                  projectOwnerUsername={projectOwnerUsername}
                  highlightedContentIndices={highlightMap.get(message.uuid)}
                  onDeleteMessage={() => handleDeleteMessage(message.uuid)}
                  onUpdateContentBlock={(contentIndex, newContent) =>
                    handleUpdateContentBlock(message.uuid, contentIndex, newContent)
                  }
                  onDeleteContentBlock={(contentIndex) =>
                    handleDeleteContentBlock(message.uuid, contentIndex)
                  }
                />
              </div>
            ))}
          </div>
        </div>
      </ScrollArea>
    </div>
  );
}

packages/cwc-website/src/views/CodingSessionEditor/hooks/useCodingSessionEditorData.ts

import { useState, useEffect } from 'react';
import type { CwcCodingSession, CwcSessionData } from 'cwc-types';
import { useConfig, useAuth } from '@/hooks';
import { clientGetCodingSession, clientGetSessionData, clientGetUser } from '@/clientApi';

/**
 * Editor data loaded from API
 */
export type EditorData = {
  projectId: string;
  session: CwcCodingSession;
  sessionData: CwcSessionData;
  projectOwnerUsername?: string;
};

/**
 * State for the editor data loading
 */
export type EditorDataState =
  | { status: 'loading' }
  | { status: 'error'; error: string }
  | { status: 'unauthorized'; message: string }
  | { status: 'ready'; data: EditorData };

/**
 * Hook to load coding session editor data client-side
 *
 * Fetches session metadata and content after component mount using
 * external API URLs and client-side gzip decompression.
 */
export function useCodingSessionEditorData(
  projectId: string | undefined,
  sessionId: string | undefined
): EditorDataState {
  const config = useConfig();
  const { isAuthenticated, login } = useAuth();
  const [state, setState] = useState<EditorDataState>({ status: 'loading' });

  useEffect(() => {
    // Validate params
    if (!projectId || !sessionId) {
      setState({ status: 'error', error: 'Project ID and Session ID are required' });
      return;
    }

    // Check authentication
    if (!isAuthenticated || !login) {
      setState({ status: 'unauthorized', message: 'You must be logged in to edit sessions' });
      return;
    }

    // Reset to loading state when params change
    setState({ status: 'loading' });

    // Fetch data
    const loadData = async (): Promise<void> => {
      try {
        // Fetch session metadata
        const sessionResult = await clientGetCodingSession(config.apiUriExternal, sessionId);

        if (!sessionResult.success) {
          setState({ status: 'error', error: 'Coding session not found' });
          return;
        }

        const session = sessionResult.data;

        // Verify user owns the project
        const userOwnsProject = login.ownedProjects.includes(session.projectId);
        if (!userOwnsProject) {
          setState({
            status: 'unauthorized',
            message: 'You do not have permission to edit this session',
          });
          return;
        }

        // Check storage key exists
        if (!session.storageKey) {
          setState({ status: 'error', error: 'Session content not available' });
          return;
        }

        // Fetch session data (content)
        const sessionData = await clientGetSessionData(
          config.contentUriExternal,
          projectId,
          session.storageKey
        );

        if (!sessionData) {
          setState({ status: 'error', error: 'Failed to load session content' });
          return;
        }

        // Fetch project owner username
        const userResult = await clientGetUser(config.apiUriExternal, session.userPkId);
        const projectOwnerUsername = userResult.success ? userResult.data.username : undefined;

        // Success
        setState({
          status: 'ready',
          data: {
            projectId,
            session,
            sessionData,
            projectOwnerUsername,
          },
        });
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
        setState({ status: 'error', error: errorMessage });
      }
    };

    loadData();
  }, [projectId, sessionId, config.apiUriExternal, config.contentUriExternal, isAuthenticated, login]);

  return state;
}

packages/cwc-website/src/views/CodingSessionEditor/index.ts

export { default as CodingSessionEditor } from './CodingSessionEditor';

packages/cwc-website/src/views/server/CodingSession/CodingSession.tsx

import type { ReactNode } from 'react';
import type { CwcCodingSession, CwcSessionData, CwcSessionMessage } from 'cwc-types';
import { CodingSessionLayout } from './CodingSessionLayout';
export { codingSessionLoader as loader } from './codingSessionLoader';

type PaginationInfo = {
  currentPage: number;
  totalPages: number;
  totalMessages: number;
};

type CodingSessionProps = {
  loaderData: {
    codingSessionPkId: number;
    projectId: string;
    session: CwcCodingSession;
    sessionData: CwcSessionData;
    messages: CwcSessionMessage[];
    projectOwnerUsername?: string;
    pagination: PaginationInfo;
  };
};

/**
 * Coding session page (page 1)
 */
export default function CodingSession({ loaderData }: CodingSessionProps): ReactNode {
  const { codingSessionPkId, projectId, session, sessionData, messages, projectOwnerUsername, pagination } = loaderData;

  return (
    <CodingSessionLayout
      codingSessionPkId={codingSessionPkId}
      projectId={projectId}
      session={session}
      sessionData={sessionData}
      messages={messages}
      projectOwnerUsername={projectOwnerUsername}
      pagination={pagination}
    />
  );
}

packages/cwc-website/src/views/server/CodingSession/CodingSessionLayout.tsx

2 versions

Version 1

import type { ReactNode } from 'react';
import type { CwcCodingSession, CwcSessionData, CwcSessionMessage } from 'cwc-types';
import { Link } from 'react-router';
import { ArrowLeft, Sun, Moon } from 'lucide-react';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@/components/ui/resizable';
import { useTheme } from '@/hooks';
import { ConversationViewer } from './conversation';
import { FileViewer } from './files';

// split-view defaults
// Left panel - Conversation (30% default) */}
const leftPanelDefaultSize = 50; // once we fix the conversation content rendering set to 30
// Right panel - Files (70% default) '
const rightPanelDefaultSize = 50; // once we fix the conversation content rendering set to 70

type PaginationInfo = {
  currentPage: number;
  totalPages: number;
  totalMessages: number;
};

type CodingSessionLayoutProps = {
  codingSessionPkId: number;
  projectId: string;
  session: CwcCodingSession;
  sessionData: CwcSessionData;
  messages: CwcSessionMessage[];
  projectOwnerUsername?: string;
  pagination: PaginationInfo;
};

export function CodingSessionLayout({
  codingSessionPkId,
  projectId,
  session,
  sessionData,
  messages,
  projectOwnerUsername,
  pagination,
}: CodingSessionLayoutProps): ReactNode {
  const { resolvedTheme, setTheme } = useTheme();

  const toggleTheme = (): void => {
    setTheme(resolvedTheme === 'dark' ? 'light' : 'dark');
  };

  // Session title - use description from database, fallback to truncated session ID
  const sessionTitle = session.description || `Session ${session.sessionId.slice(0, 8)}...`;

  return (
    <div className="flex flex-col h-screen overflow-hidden">
      {/* Integrated header - site branding, session info, and controls */}
      <header className="flex items-center gap-3 border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60 px-4 h-14 shrink-0">
        {/* Site branding */}
        <Link to="/" className="text-xl font-bold shrink-0">
          Coding with Claude
        </Link>

        {/* Separator */}
        <span className="text-muted-foreground">/</span>

        {/* Back to project */}
        <Link
          to={`/project/${projectId}`}
          className="text-muted-foreground hover:text-foreground transition-colors shrink-0 flex items-center gap-1"
          title="Back to project"
        >
          <ArrowLeft className="h-4 w-4" />
          <span className="text-sm hidden sm:inline">Project</span>
        </Link>

        {/* Session title */}
        <span
          className="text-sm font-medium truncate flex-1 text-muted-foreground"
          title={sessionTitle}
        >
          {sessionTitle}
        </span>

        {/* Badges and controls */}
        <div className="flex items-center gap-2 shrink-0">
          <Badge variant="secondary" className="text-xs hidden sm:flex">
            {sessionData.files.length} files
          </Badge>
          <Badge variant="outline" className="text-xs hidden sm:flex">
            {sessionData.stats.totalMessages} messages
          </Badge>
          <Button
            variant="ghost"
            size="sm"
            onClick={toggleTheme}
            className="h-9 w-9 p-0"
            title={`Switch to ${resolvedTheme === 'dark' ? 'light' : 'dark'} mode`}
          >
            {resolvedTheme === 'dark' ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
          </Button>
        </div>
      </header>

      {/* Large screens: side-by-side with ResizablePanelGroup */}
      <div className="hidden lg:flex flex-1 min-h-0 overflow-hidden">
        <ResizablePanelGroup orientation="horizontal" className="flex-1">
          <ResizablePanel defaultSize={leftPanelDefaultSize} minSize={10}>
            <ConversationViewer
              projectId={projectId}
              sessionId={session.sessionId}
              messages={messages}
              projectOwnerUsername={projectOwnerUsername}
              pagination={pagination}
            />
          </ResizablePanel>

          <ResizableHandle withHandle />

          <ResizablePanel defaultSize={rightPanelDefaultSize} minSize={10}>
            <FileViewer session={session} sessionData={sessionData} />
          </ResizablePanel>
        </ResizablePanelGroup>
      </div>

      {/* Small screens: stacked vertically */}
      <div className="flex lg:hidden flex-col flex-1 min-h-0 overflow-hidden">
        <div className="flex-1 min-h-0 overflow-hidden">
          <ConversationViewer
            projectId={projectId}
            sessionId={session.sessionId}
            messages={messages}
            projectOwnerUsername={projectOwnerUsername}
            pagination={pagination}
          />
        </div>
        <div className="flex-1 min-h-0 overflow-hidden border-t">
          <FileViewer session={session} sessionData={sessionData} />
        </div>
      </div>
    </div>
  );
}

Version 2 (latest)

import type { ReactNode } from 'react';
import type { CwcCodingSession, CwcSessionData, CwcSessionMessage } from 'cwc-types';
import { Link } from 'react-router';
import { ArrowLeft, Sun, Moon } from 'lucide-react';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@/components/ui/resizable';
import { useTheme } from '@/hooks';
import { ConversationViewer } from './conversation';
import { FileViewer } from './files';

// split-view defaults
// Left panel - Conversation (30% default) */}
const leftPanelDefaultSize = 50; // once we fix the conversation content rendering set to 30
// Right panel - Files (70% default) '
const rightPanelDefaultSize = 50; // once we fix the conversation content rendering set to 70

type PaginationInfo = {
  currentPage: number;
  totalPages: number;
  totalMessages: number;
};

type CodingSessionLayoutProps = {
  codingSessionPkId: number;
  projectId: string;
  session: CwcCodingSession;
  sessionData: CwcSessionData;
  messages: CwcSessionMessage[];
  projectOwnerUsername?: string;
  pagination: PaginationInfo;
};

export function CodingSessionLayout({
  codingSessionPkId,
  projectId,
  session,
  sessionData,
  messages,
  projectOwnerUsername,
  pagination,
}: CodingSessionLayoutProps): ReactNode {
  const { resolvedTheme, setTheme } = useTheme();

  const toggleTheme = (): void => {
    setTheme(resolvedTheme === 'dark' ? 'light' : 'dark');
  };

  // Session title - use description from database, fallback to truncated session ID
  const sessionTitle = session.description || `Session ${session.sessionId.slice(0, 8)}...`;

  return (
    <div className="flex flex-col h-screen overflow-hidden">
      {/* Integrated header - site branding, session info, and controls */}
      <header className="flex items-center gap-3 border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60 px-4 h-14 shrink-0">
        {/* Site branding */}
        <Link to="/" className="text-xl font-bold shrink-0">
          Coding with Claude
        </Link>

        {/* Separator */}
        <span className="text-muted-foreground">/</span>

        {/* Back to project */}
        <Link
          to={`/project/${projectId}`}
          className="text-muted-foreground hover:text-foreground transition-colors shrink-0 flex items-center gap-1"
          title="Back to project"
        >
          <ArrowLeft className="h-4 w-4" />
          <span className="text-sm hidden sm:inline">Project</span>
        </Link>

        {/* Session title */}
        <span
          className="text-sm font-medium truncate flex-1 text-muted-foreground"
          title={sessionTitle}
        >
          {sessionTitle}
        </span>

        {/* Badges and controls */}
        <div className="flex items-center gap-2 shrink-0">
          <Badge variant="secondary" className="text-xs hidden sm:flex">
            {sessionData.files.length} files
          </Badge>
          <Badge variant="outline" className="text-xs hidden sm:flex">
            {sessionData.stats.totalMessages} messages
          </Badge>
          <Button
            variant="ghost"
            size="sm"
            onClick={toggleTheme}
            className="h-9 w-9 p-0"
            title={`Switch to ${resolvedTheme === 'dark' ? 'light' : 'dark'} mode`}
          >
            {resolvedTheme === 'dark' ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
          </Button>
        </div>
      </header>

      {/* Large screens: side-by-side with ResizablePanelGroup */}
      <div className="hidden lg:flex flex-1 min-h-0 overflow-hidden">
        <ResizablePanelGroup orientation="horizontal" className="flex-1">
          <ResizablePanel defaultSize={leftPanelDefaultSize} minSize={10}>
            <ConversationViewer
              codingSessionPkId={codingSessionPkId}
              messages={messages}
              projectOwnerUsername={projectOwnerUsername}
              pagination={pagination}
            />
          </ResizablePanel>

          <ResizableHandle withHandle />

          <ResizablePanel defaultSize={rightPanelDefaultSize} minSize={10}>
            <FileViewer session={session} sessionData={sessionData} />
          </ResizablePanel>
        </ResizablePanelGroup>
      </div>

      {/* Small screens: stacked vertically */}
      <div className="flex lg:hidden flex-col flex-1 min-h-0 overflow-hidden">
        <div className="flex-1 min-h-0 overflow-hidden">
          <ConversationViewer
            codingSessionPkId={codingSessionPkId}
            messages={messages}
            projectOwnerUsername={projectOwnerUsername}
            pagination={pagination}
          />
        </div>
        <div className="flex-1 min-h-0 overflow-hidden border-t">
          <FileViewer session={session} sessionData={sessionData} />
        </div>
      </div>
    </div>
  );
}

packages/cwc-website/src/views/server/CodingSession/codingSessionLoader.ts

2 versions

Version 1

import type { Route } from './+types/CodingSession';
import { getCodingSession, getSessionData, getUser } from '@/server';
import {
  calculatePagination,
  getCachedPagination,
  getMessagesForPage,
  type SessionPaginationInfo,
} from '@/prerender';

/**
 * Loader for the base coding session route (page 1)
 */
export async function codingSessionLoader({ params }: Route.LoaderArgs) {
  const { projectId, sessionId } = params;

  if (!projectId) {
    throw new Response('Project ID is required', { status: 400 });
  }

  if (!sessionId) {
    throw new Response('Session ID is required', { status: 400 });
  }

  // Fetch session metadata from cwc-api
  const sessionResult = await getCodingSession(sessionId);

  if (!sessionResult.success) {
    throw new Response('Coding session not found', { status: 404 });
  }

  const session = sessionResult.data;

  // Fetch session data from cwc-content
  if (!session.storageKey) {
    throw new Response('Session content not available', { status: 404 });
  }

  const sessionData = await getSessionData(projectId, session.storageKey);

  if (!sessionData) {
    throw new Response('Failed to load session content', { status: 500 });
  }

  // Fetch project owner info
  const userResult = await getUser(session.userPkId);
  const projectOwnerUsername = userResult.success ? userResult.data.username : undefined;

  // Get or calculate pagination
  let paginationInfo: SessionPaginationInfo | undefined = getCachedPagination(sessionId);

  if (!paginationInfo) {
    paginationInfo = calculatePagination(sessionData);
  }

  // Get messages for page 1 (this is the base route)
  const currentPage = 1;
  const messages = getMessagesForPage(sessionData, currentPage, paginationInfo);

  return {
    projectId,
    session,
    sessionData,
    messages,
    projectOwnerUsername,
    pagination: {
      currentPage,
      totalPages: paginationInfo.totalPages,
      totalMessages: paginationInfo.totalMessages,
    },
  };
}

Version 2 (latest)

import type { Route } from './+types/CodingSession';
import { getCodingSession, getProjectByPkId, getSessionData, getUser } from '@/server';
import {
  calculatePagination,
  getCachedPagination,
  getMessagesForPage,
  type SessionPaginationInfo,
} from '@/prerender';

/**
 * Loader for the base coding session route (page 1)
 *
 * URL: /session/:codingSessionPkId
 * Fetches session by codingSessionPkId, then derives project info from session.projectPkId
 */
export async function codingSessionLoader({ params }: Route.LoaderArgs) {
  const { codingSessionPkId: pkIdParam } = params;

  if (!pkIdParam) {
    throw new Response('codingSessionPkId is required', { status: 400 });
  }

  const codingSessionPkId = parseInt(pkIdParam, 10);

  if (isNaN(codingSessionPkId)) {
    throw new Response('Invalid codingSessionPkId', { status: 400 });
  }

  // Fetch session metadata from cwc-api
  const sessionResult = await getCodingSession(codingSessionPkId);

  if (!sessionResult.success) {
    throw new Response('Coding session not found', { status: 404 });
  }

  const session = sessionResult.data;

  // Fetch project to get projectId (needed for storage lookups)
  const projectResult = await getProjectByPkId(session.projectPkId);

  if (!projectResult.success) {
    throw new Response('Project not found', { status: 404 });
  }

  const project = projectResult.data;
  const projectId = project.projectId;

  // Fetch session data from cwc-content
  if (!session.storageKey) {
    throw new Response('Session content not available', { status: 404 });
  }

  const sessionData = await getSessionData(projectId, session.storageKey);

  if (!sessionData) {
    throw new Response('Failed to load session content', { status: 500 });
  }

  // Fetch project owner info
  const userResult = await getUser(session.userPkId);
  const projectOwnerUsername = userResult.success ? userResult.data.username : undefined;

  // Get or calculate pagination (keyed by codingSessionPkId)
  let paginationInfo: SessionPaginationInfo | undefined = getCachedPagination(codingSessionPkId);

  if (!paginationInfo) {
    paginationInfo = calculatePagination(codingSessionPkId, sessionData);
  }

  // Get messages for page 1 (this is the base route)
  const currentPage = 1;
  const messages = getMessagesForPage(sessionData, currentPage, paginationInfo);

  return {
    codingSessionPkId,
    projectId,
    session,
    sessionData,
    messages,
    projectOwnerUsername,
    pagination: {
      currentPage,
      totalPages: paginationInfo.totalPages,
      totalMessages: paginationInfo.totalMessages,
    },
  };
}

packages/cwc-website/src/views/server/CodingSession/CodingSessionPage.tsx

import type { ReactNode } from 'react';
import type { CwcCodingSession, CwcSessionData, CwcSessionMessage } from 'cwc-types';
import { CodingSessionLayout } from './CodingSessionLayout';
export { codingSessionPageLoader as loader } from './codingSessionPageLoader';

type PaginationInfo = {
  currentPage: number;
  totalPages: number;
  totalMessages: number;
};

type CodingSessionPageProps = {
  loaderData: {
    codingSessionPkId: number;
    projectId: string;
    session: CwcCodingSession;
    sessionData: CwcSessionData;
    messages: CwcSessionMessage[];
    projectOwnerUsername?: string;
    pagination: PaginationInfo;
  };
};

/**
 * Paginated coding session page (page 2+)
 *
 * This is a child route of CodingSession, handling /page/:pageNumber
 */
export default function CodingSessionPage({ loaderData }: CodingSessionPageProps): ReactNode {
  const { codingSessionPkId, projectId, session, sessionData, messages, projectOwnerUsername, pagination } = loaderData;

  return (
    <CodingSessionLayout
      codingSessionPkId={codingSessionPkId}
      projectId={projectId}
      session={session}
      sessionData={sessionData}
      messages={messages}
      projectOwnerUsername={projectOwnerUsername}
      pagination={pagination}
    />
  );
}

packages/cwc-website/src/views/server/CodingSession/codingSessionPageLoader.ts

2 versions

Version 1

import { redirect } from 'react-router';
import type { Route } from './+types/CodingSessionPage';
import { getCodingSession, getSessionData, getUser } from '@/server';
import {
  calculatePagination,
  getCachedPagination,
  getMessagesForPage,
  type SessionPaginationInfo,
} from '@/prerender';

export async function codingSessionPageLoader({ params }: Route.LoaderArgs) {
  const { projectId, sessionId, pageNumber } = params;

  if (!projectId) {
    throw new Response('Project ID is required', { status: 400 });
  }

  if (!sessionId) {
    throw new Response('Session ID is required', { status: 400 });
  }

  if (!pageNumber) {
    throw new Response('Page number is required', { status: 400 });
  }

  // Parse page number
  const currentPage = parseInt(pageNumber, 10);

  // Redirect /page/1 to base URL to avoid duplicate content
  if (pageNumber === '1') {
    throw redirect(`/project/${projectId}/session/${sessionId}`);
  }

  // Fetch session metadata from cwc-api
  const sessionResult = await getCodingSession(sessionId);

  if (!sessionResult.success) {
    throw new Response('Coding session not found', { status: 404 });
  }

  const session = sessionResult.data;

  // Fetch session data from cwc-content
  if (!session.storageKey) {
    throw new Response('Session content not available', { status: 404 });
  }

  const sessionData = await getSessionData(projectId, session.storageKey);

  if (!sessionData) {
    throw new Response('Failed to load session content', { status: 500 });
  }

  // Fetch project owner info
  const userResult = await getUser(session.userPkId);
  const projectOwnerUsername = userResult.success ? userResult.data.username : undefined;

  // Get or calculate pagination
  let paginationInfo: SessionPaginationInfo | undefined = getCachedPagination(sessionId);

  if (!paginationInfo) {
    paginationInfo = calculatePagination(sessionData);
  }

  // Validate page number
  if (currentPage < 1 || currentPage > paginationInfo.totalPages) {
    throw new Response('Page not found', { status: 404 });
  }

  // Get messages for current page
  const messages = getMessagesForPage(sessionData, currentPage, paginationInfo);

  return {
    projectId,
    session,
    sessionData,
    messages,
    projectOwnerUsername,
    pagination: {
      currentPage,
      totalPages: paginationInfo.totalPages,
      totalMessages: paginationInfo.totalMessages,
    },
  };
}

Version 2 (latest)

import { redirect } from 'react-router';
import type { Route } from './+types/CodingSessionPage';
import { getCodingSession, getProjectByPkId, getSessionData, getUser } from '@/server';
import {
  calculatePagination,
  getCachedPagination,
  getMessagesForPage,
  type SessionPaginationInfo,
} from '@/prerender';

/**
 * Loader for paginated coding session route
 *
 * URL: /session/:codingSessionPkId/page/:pageNumber
 * Fetches session by codingSessionPkId, then derives project info from session.projectPkId
 */
export async function codingSessionPageLoader({ params }: Route.LoaderArgs) {
  const { codingSessionPkId: pkIdParam, pageNumber } = params;

  if (!pkIdParam) {
    throw new Response('codingSessionPkId is required', { status: 400 });
  }

  if (!pageNumber) {
    throw new Response('Page number is required', { status: 400 });
  }

  const codingSessionPkId = parseInt(pkIdParam, 10);

  if (isNaN(codingSessionPkId)) {
    throw new Response('Invalid codingSessionPkId', { status: 400 });
  }

  // Parse page number
  const currentPage = parseInt(pageNumber, 10);

  // Redirect /page/1 to base URL to avoid duplicate content
  if (pageNumber === '1') {
    throw redirect(`/session/${codingSessionPkId}`);
  }

  // Fetch session metadata from cwc-api
  const sessionResult = await getCodingSession(codingSessionPkId);

  if (!sessionResult.success) {
    throw new Response('Coding session not found', { status: 404 });
  }

  const session = sessionResult.data;

  // Fetch project to get projectId (needed for storage lookups)
  const projectResult = await getProjectByPkId(session.projectPkId);

  if (!projectResult.success) {
    throw new Response('Project not found', { status: 404 });
  }

  const project = projectResult.data;
  const projectId = project.projectId;

  // Fetch session data from cwc-content
  if (!session.storageKey) {
    throw new Response('Session content not available', { status: 404 });
  }

  const sessionData = await getSessionData(projectId, session.storageKey);

  if (!sessionData) {
    throw new Response('Failed to load session content', { status: 500 });
  }

  // Fetch project owner info
  const userResult = await getUser(session.userPkId);
  const projectOwnerUsername = userResult.success ? userResult.data.username : undefined;

  // Get or calculate pagination (keyed by codingSessionPkId)
  let paginationInfo: SessionPaginationInfo | undefined = getCachedPagination(codingSessionPkId);

  if (!paginationInfo) {
    paginationInfo = calculatePagination(codingSessionPkId, sessionData);
  }

  // Validate page number
  if (currentPage < 1 || currentPage > paginationInfo.totalPages) {
    throw new Response('Page not found', { status: 404 });
  }

  // Get messages for current page
  const messages = getMessagesForPage(sessionData, currentPage, paginationInfo);

  return {
    codingSessionPkId,
    projectId,
    session,
    sessionData,
    messages,
    projectOwnerUsername,
    pagination: {
      currentPage,
      totalPages: paginationInfo.totalPages,
      totalMessages: paginationInfo.totalMessages,
    },
  };
}

packages/cwc-website/src/views/server/CodingSession/conversation/ConversationViewer.tsx

import type { ReactNode } from 'react';
import type { CwcSessionMessage } from 'cwc-types';
import { ScrollArea } from '@/components/ui/scroll-area';
import { MessageBlock } from './MessageBlock';
import { PaginationNav } from './PaginationNav';

type PaginationInfo = {
  currentPage: number;
  totalPages: number;
  totalMessages: number;
};

type ConversationViewerProps = {
  codingSessionPkId: number;
  messages: CwcSessionMessage[];
  projectOwnerUsername?: string;
  pagination: PaginationInfo;
};

/**
 * Conversation viewer for coding session transcripts
 *
 * Displays messages between user and Claude with pagination.
 */
export function ConversationViewer({
  codingSessionPkId,
  messages,
  projectOwnerUsername,
  pagination,
}: ConversationViewerProps): ReactNode {
  return (
    <div className="h-full w-full overflow-hidden">
      <ScrollArea className="h-full w-full">
        <div className="p-4 space-y-4 max-w-full overflow-hidden">
        {messages.length > 0 ? (
          <>
            {messages.map((message) => (
              <MessageBlock key={message.uuid} message={message} projectOwnerUsername={projectOwnerUsername} />
            ))}
            <PaginationNav
              codingSessionPkId={codingSessionPkId}
              currentPage={pagination.currentPage}
              totalPages={pagination.totalPages}
            />
          </>
        ) : (
          <p className="text-muted-foreground">No content available for this session.</p>
        )}
        </div>
      </ScrollArea>
    </div>
  );
}

packages/cwc-website/src/views/server/CodingSession/conversation/PaginationNav.tsx

import type { ReactNode } from 'react';
import { Link } from 'react-router';
import { ChevronLeft, ChevronRight } from 'lucide-react';
import { Button } from '@/components/ui/button';

type PaginationNavProps = {
  codingSessionPkId: number;
  currentPage: number;
  totalPages: number;
};

/**
 * Get the URL for a specific page
 *
 * Page 1 uses the base URL (canonical), pages 2+ use /page/:pageNumber
 */
function getPageUrl(codingSessionPkId: number, page: number): string {
  const baseUrl = `/session/${codingSessionPkId}`;
  if (page === 1) {
    return baseUrl;
  }
  return `${baseUrl}/page/${page}`;
}

/**
 * Pagination navigation for coding session pages
 *
 * Displays previous/next buttons and current page indicator.
 * Only shown when there are multiple pages.
 */
export function PaginationNav({
  codingSessionPkId,
  currentPage,
  totalPages,
}: PaginationNavProps): ReactNode {
  // Don't render if only one page
  if (totalPages <= 1) {
    return null;
  }

  return (
    <nav className="flex items-center justify-between py-4 border-t mt-4">
      <div>
        {currentPage > 1 && (
          <Button variant="outline" asChild>
            <Link to={getPageUrl(codingSessionPkId, currentPage - 1)}>
              <ChevronLeft className="h-4 w-4 mr-2" />
              Previous
            </Link>
          </Button>
        )}
      </div>

      <span className="text-sm text-muted-foreground">
        Page {currentPage} of {totalPages}
      </span>

      <div>
        {currentPage < totalPages && (
          <Button variant="outline" asChild>
            <Link to={getPageUrl(codingSessionPkId, currentPage + 1)}>
              Next
              <ChevronRight className="h-4 w-4 ml-2" />
            </Link>
          </Button>
        )}
      </div>
    </nav>
  );
}

packages/cwc-website/src/views/server/Home/content.ts

import { CwcWebsiteConfig } from '@/config';

export type TileContent = {
  title: string;
  subtitle: string;
  url: string | undefined;
};

export type GetTileContentOptions = {
  config: CwcWebsiteConfig;
};

export const getTileContent = ({ config }: GetTileContentOptions): TileContent[] => {
  // Show minimal landing page (no links to other pages) when websiteContentMode is 'Minimal'
  // This is controlled per environment in cwc-configuration-helper
  const isMinimal = config.websiteContentMode === 'Minimal';

  return [
    {
      title: 'Build a website with Claude Code',
      subtitle:
        'This website, backend services, configuration, and utilities were built from scratch while pairing with Claude Code',
      url: isMinimal ? undefined : '/project/coding-with-claude',
    },

    {
      title: 'Real-world Projects',
      subtitle: 'Realistic software projects leveraging AI-assisted coding with Claude Code',
      url: isMinimal ? undefined : '/projects',
    },
    {
      title: 'In-depth Coding Sessions',
      subtitle:
        'Claude Code planning & development sessions including prompts, analysis, recommendations, and coding',
      url: isMinimal ? undefined : '/projects',
    },
    {
      title: 'Professional Software Engineers',
      subtitle: 'See how professional developers work with Claude Code to increase productivity',
      url: isMinimal ? undefined : '/projects',
    },
    {
      title: 'Software Architecture',
      subtitle: 'Learn how Claude Code can help you design and architect your apps',
      url: isMinimal ? undefined : '/projects',
    },

    {
      title: 'Microservices',
      subtitle: 'Learn about cloud-agnostic architecture with Docker containers and Docker Compose',
      url: isMinimal ? undefined : '/project/coding-with-claude',
    },
    {
      title: 'TypeScript',
      subtitle: 'Full-stack TypeScript with React, React Router v7, Node.js, and MariaDB',
      url: isMinimal ? undefined : '/project/coding-with-claude',
    },
  ];
};

packages/cwc-website/src/views/server/Project/codingSessionColumn.tsx

import type { ColumnDef } from '@tanstack/react-table';
import type { CwcCodingSession } from 'cwc-types';
import { Link } from 'react-router';
import { Edit2 } from 'lucide-react';

type CodingSessionColumnOptions = {
  showEditColumn?: boolean;
};

/**
 * Format a timestamp to a locale date string (no time)
 */
function formatDate(timestamp: string): string {
  return new Date(timestamp).toLocaleDateString();
}

export function getCodingSessionColumns(
  options: CodingSessionColumnOptions = {}
): ColumnDef<CwcCodingSession>[] {
  const columns: ColumnDef<CwcCodingSession>[] = [
    {
      accessorKey: 'startTimestamp',
      header: 'Date',
      cell: ({ row }) => formatDate(row.original.startTimestamp),
    },
    {
      accessorKey: 'description',
      header: 'Description',
      cell: ({ row }) => (
        <Link
          to={`/session/${row.original.codingSessionPkId}`}
          className="font-medium text-foreground hover:underline"
        >
          {row.original.description}
        </Link>
      ),
    },
    {
      accessorKey: 'messageCount',
      header: 'Messages',
    },
    {
      accessorKey: 'filesModifiedCount',
      header: 'Files Modified',
    },
  ];

  // Add edit column if enabled (for project owners)
  if (options.showEditColumn) {
    columns.push({
      id: 'actions',
      header: '',
      cell: ({ row }) => (
        <Link
          to={`/session-editor/${row.original.codingSessionPkId}`}
          className="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground"
          title="Edit session"
        >
          <Edit2 className="h-4 w-4" />
        </Link>
      ),
    });
  }

  return columns;
}

packages/cwc-website/src/views/server/Project/CodingSessionList.tsx

import type { ReactNode } from 'react';
import type { CwcCodingSession } from 'cwc-types';
import { DataTable } from '@/components/DataTable';
import { getCodingSessionColumns } from './codingSessionColumn';

type CodingSessionListProps = {
  sessionList: CwcCodingSession[];
  showEditColumn?: boolean;
};

export function CodingSessionList({
  sessionList,
  showEditColumn,
}: CodingSessionListProps): ReactNode {
  const columns = getCodingSessionColumns({ showEditColumn });

  return (
    <DataTable
      columns={columns}
      data={sessionList}
      emptyMessage="No published coding sessions yet."
    />
  );
}

packages/cwc-website/src/views/server/Project/Project.tsx

import type { ReactNode } from 'react';
import type { CwcProject, CwcCodingSession } from 'cwc-types';
import { useAuth } from '@/hooks';
import { CodingSessionList } from './CodingSessionList';
export { projectLoader as loader } from './projectLoader';

type ProjectProps = {
  loaderData: { project: CwcProject; sessionList: CwcCodingSession[] };
};

export default function Project({ loaderData }: ProjectProps): ReactNode {
  const { project, sessionList } = loaderData;
  const { login } = useAuth();

  // Check if the logged-in user owns this project
  const isProjectOwner = login?.ownedProjects?.includes(project.projectId) ?? false;

  return (
    <div className="container py-8">
      <header className="mb-8">
        <h1 className="text-3xl font-bold mb-2">{project.projectId}</h1>
        <p className="text-muted-foreground capitalize">{project.projectType} project</p>
      </header>

      <section>
        <h2 className="text-2xl font-semibold mb-4">Coding Sessions</h2>
        <CodingSessionList
          sessionList={sessionList}
          showEditColumn={isProjectOwner}
        />
      </section>
    </div>
  );
}

packages/cwc-website/src/views/server/Project/projectLoader.ts

import type { Route } from './+types/Project';
import { getProject, getCodingSessionList } from '@/server';

export async function projectLoader({ params }: Route.LoaderArgs) {
  const projectId = params.projectId;

  if (!projectId) {
    throw new Response('Project ID is required', { status: 400 });
  }

  const projectResult = await getProject(projectId);

  if (!projectResult.success) {
    throw new Response('Project not found', { status: 404 });
  }

  const sessionListResult = await getCodingSessionList(projectResult.data.projectPkId, {
    pageSize: 1000,
  });

  // Sort by startTimestamp (oldest first)
  const sessionList = sessionListResult.success
    ? [...sessionListResult.data].sort(
        (a, b) => new Date(a.startTimestamp).getTime() - new Date(b.startTimestamp).getTime()
      )
    : [];

  return {
    project: projectResult.data,
    sessionList,
  };
}

packages/cwc-website/src/views/server/ProjectList/projectListLoader.ts

import { getProjectList } from '@/server';

export async function projectListLoader() {
  const result = await getProjectList();

  if (!result.success) {
    throw new Response('Failed to load projects', { status: 500 });
  }

  return { projectList: result.data };
}

packages/cwc-website/tsconfig.json

{
  "include": [
    "**/*.ts",
    "**/*.tsx",
    ".react-router/types/**/*"
  ],
  "exclude": ["node_modules", "dist", "build"],
  "compilerOptions": {
    "lib": ["DOM", "DOM.Iterable", "ES2022"],
    "types": ["@react-router/node", "vite/client", "@testing-library/jest-dom"],
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "strict": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "noEmit": true,

    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "rootDirs": [".", "./.react-router/types"]
  }
}

Session 45: website improvements

Session 45: website improvements

Session 45: website improvements

Plan: Item 1 - Client-Side CodingSessionEditor & View Organization

Problem Summary

Key Concepts

Implementation Plan

Part A: Convert CodingSessionEditor to Purely Client-Side

Part B: Organize Views into Folders

Part C: Update routes.ts

Questions Resolved

Execution Order

Part B: Organize Views into Subfolders

Part C: Update routes.ts

Execution Order

Deferred to Item 2 (Pagination)

Part A: Convert CodingSessionEditor to Purely Client-Side

Part B: Reorganize Views

Part C: Updated routes.ts

Test Setup Complete

Jest Configuration

Key ESM Pattern Discovered

Tests Created

Files Created/Modified

Current State Summary

Plan: Migrate from sessionId (UUID) to codingSessionPkId in URLs

Problem Summary

Target State

Phase 1: cwc-api Changes

1.1 Update API Payload Type

1.2 Update GET Handler

Phase 2: cwc-website Routes

2.1 Update Route Definitions

Phase 3: Server-Side Loaders

3.1 Update codingSessionLoader.ts

3.2 Update codingSessionPageLoader.ts

3.3 Update Server API Function

Phase 4: Client-Side Changes

4.1 Update Client API

4.2 Update useCodingSessionEditorData Hook

4.3 Update CodingSessionEditor Component

Phase 5: Link Construction

Phase 6: SSG Prerender

6.1 Update prerender.ts

6.2 Update sessionPagination.ts

Phase 7: Test Updates

Files to Update:

Changes:

Execution Order

Notes

Migration: sessionId → codingSessionPkId

Plan: Simplify Session URLs with codingSessionPkId

Problem Summary

Target State

Why This Works

Phase 2: cwc-website Routes

2.1 Update Route Definitions

Phase 3: Server-Side Loaders

3.1 Update codingSessionLoader.ts

3.2 Update codingSessionPageLoader.ts

3.3 Update Server API Functions

3.4 Add getProjectByPkId (if not exists)

Phase 5: Link Construction

Phase 6: SSG Prerender

6.1 Update prerender.ts

6.2 Update sessionPagination.ts

Notes

cwc-api: Check if getProjectByPkId Exists

Decision: How to Fetch Related Entity Data

Option A: Database View (codingSessionInfo)

Option B: Modify getProject to accept PkId OR projectId

Option C: Extend getCodingSession response (JOIN in handler)

Option D: Create composite endpoint (getCodingSessionDetail)

Option E: Parallel fetches in cwc-website

Recommended: Option B (Modify getProject)

CHOSEN: Option B (Modify getProject)

URL Summary

URL Summary

Phase 5: Link Construction

4.3 Update CodingSessionEditor Component

Option A: Database View (`codingSessionInfo`)

Option B: Modify `getProject` to accept PkId OR projectId

Option C: Extend `getCodingSession` response (JOIN in handler)

Option D: Create composite endpoint (`getCodingSessionDetail`)

Issue 1: Missing Protocol in `corsOrigin`