Mikkel Georgsen
af211e6a39
4 plans across 3 waves for Chat Foundation phase. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
23 KiB
23 KiB
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 21-chat-foundation | 01 | execute | 1 |
|
true |
|
|
Purpose: Establishes the persistence and API foundation that all UI components in subsequent plans depend on. Without this, no conversation can be created, stored, or retrieved. Output: Two new Drizzle schema files, a migration, shared types + validators, service + route factories, and automated tests.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/21-chat-foundation/21-RESEARCH.mdFrom packages/db/src/schema/documents.ts (reference pattern for new schema):
import { pgTable, uuid, text, timestamp, index } from "drizzle-orm/pg-core";
import { companies } from "./companies.js";
export const documents = pgTable(
"documents",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id),
// ... columns
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
},
(table) => ({
companyUpdatedIdx: index("documents_company_updated_idx").on(table.companyId, table.updatedAt),
}),
);
From server/src/routes/activity.ts (reference pattern for route factory):
export function activityRoutes(db: Db) {
const router = Router();
const svc = activityService(db);
router.get("/companies/:companyId/activity", async (req, res) => {
assertBoard(req);
assertCompanyAccess(req, req.params.companyId!);
const result = await svc.list(filters);
res.json(result);
});
return router;
}
From server/src/tests/activity-routes.test.ts (reference test pattern):
const mockActivityService = vi.hoisted(() => ({
list: vi.fn(),
create: vi.fn(),
}));
vi.mock("../services/activity.js", () => ({
activityService: () => mockActivityService,
}));
function createApp() {
const app = express();
app.use(express.json());
app.use((req, _res, next) => {
(req as any).actor = {
type: "board", userId: "user-1", companyIds: ["company-1"], source: "session", isInstanceAdmin: false,
};
next();
});
app.use("/api", activityRoutes({} as any));
app.use(errorHandler);
return app;
}
From server/src/middleware/validate.ts:
export function validate(schema: ZodSchema) {
return (req: Request, _res: Response, next: NextFunction) => {
req.body = schema.parse(req.body);
next();
};
}
From server/src/app.ts (route mounting — line 158):
api.use(activityRoutes(db));
2. Create `packages/db/src/schema/chat_messages.ts`:
- Table name: `chat_messages`
- Columns: `id` (uuid PK defaultRandom), `conversationId` (uuid FK to chatConversations.id onDelete "cascade", NOT NULL), `role` (text NOT NULL — values: "user" | "assistant" | "system"), `content` (text NOT NULL), `agentId` (uuid, nullable — which agent produced this), `createdAt` (timestamp with tz, NOT NULL, defaultNow)
- Index: `chat_messages_conversation_created_idx` on (conversationId, createdAt)
- Export: `export const chatMessages`
3. Add to `packages/db/src/schema/index.ts` — append two lines:
```
export { chatConversations } from "./chat_conversations.js";
export { chatMessages } from "./chat_messages.js";
```
4. Run `pnpm db:generate` to generate migration SQL. Verify the generated SQL contains:
- `CREATE TABLE "chat_conversations"` with all columns
- `CREATE TABLE "chat_messages"` with `ON DELETE CASCADE` on conversation_id FK
- Both index `CREATE INDEX` statements
5. Create `packages/shared/src/types/chat.ts`:
```typescript
export interface ChatConversation {
id: string;
companyId: string;
title: string | null;
agentId: string | null;
pinnedAt: string | null;
archivedAt: string | null;
deletedAt: string | null;
createdAt: string;
updatedAt: string;
}
export interface ChatMessage {
id: string;
conversationId: string;
role: "user" | "assistant" | "system";
content: string;
agentId: string | null;
createdAt: string;
}
export interface ChatConversationListResponse {
items: ChatConversation[];
hasMore: boolean;
}
```
6. Create `packages/shared/src/validators/chat.ts`:
```typescript
import { z } from "zod";
export const createConversationSchema = z.object({
title: z.string().max(200).optional(),
});
export const updateConversationSchema = z.object({
title: z.string().max(200).optional(),
});
export const createMessageSchema = z.object({
role: z.enum(["user", "assistant", "system"]),
content: z.string().min(1),
agentId: z.string().uuid().optional().nullable(),
});
```
7. Create `server/src/services/chat.ts` following the `documentService` factory pattern:
```typescript
export function chatService(db: Db) {
return {
async listConversations(companyId: string, opts: { cursor?: string; limit?: number }) { ... },
async createConversation(companyId: string, data: { title?: string }) { ... },
async getConversation(id: string) { ... },
async updateConversation(id: string, data: { title?: string }) { ... },
async softDeleteConversation(id: string) { ... },
async archiveConversation(id: string) { ... },
async unarchiveConversation(id: string) { ... },
async pinConversation(id: string) { ... },
async unpinConversation(id: string) { ... },
async listMessages(conversationId: string, opts: { cursor?: string; limit?: number }) { ... },
async addMessage(conversationId: string, data: { role: string; content: string; agentId?: string | null }) { ... },
};
}
```
Key implementation details:
- `listConversations`: filter `WHERE companyId = $1 AND deletedAt IS NULL`, order by `updatedAt DESC`, cursor-based pagination with `updatedAt < cursor`, limit defaults to 30 (max 100), return `{ items, hasMore }` where hasMore is `rows.length > limit` and items is `rows.slice(0, limit)`
- `addMessage`: after inserting the message, run `UPDATE chat_conversations SET updated_at = now() WHERE id = $conversationId`. Also, if `conversation.title IS NULL`, set `title = content.slice(0, 60)` using `WHERE id = $conversationId AND title IS NULL` for idempotency
- `softDeleteConversation`: `UPDATE chat_conversations SET deleted_at = now() WHERE id = $id`
- `archiveConversation`: `UPDATE SET archived_at = now()`
- `pinConversation`: `UPDATE SET pinned_at = now()`
- `unpinConversation`: `UPDATE SET pinned_at = null`
8. Create `server/src/__tests__/chat-service.test.ts` using the `vi.mock` pattern from `activity-routes.test.ts`. Mock `@paperclipai/db` to provide a mock `db` object with chainable `.select().from().where().orderBy().limit()` and `.insert().values().returning()` and `.update().set().where()` methods. Test all behaviors listed in the `<behavior>` block above.
export function chatRoutes(db: Db) {
const router = Router();
const svc = chatService(db);
// GET /api/companies/:companyId/conversations
router.get("/companies/:companyId/conversations", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);
const cursor = req.query.cursor as string | undefined;
const limit = req.query.limit ? Number(req.query.limit) : undefined;
const result = await svc.listConversations(companyId, { cursor, limit });
res.json(result);
});
// POST /api/companies/:companyId/conversations
router.post("/companies/:companyId/conversations", validate(createConversationSchema), async (req, res) => {
assertBoard(req);
const companyId = req.params.companyId as string;
const conversation = await svc.createConversation(companyId, req.body);
res.status(201).json(conversation);
});
// GET /api/conversations/:id
router.get("/conversations/:id", async (req, res) => {
assertBoard(req);
const conversation = await svc.getConversation(req.params.id as string);
if (!conversation) { res.status(404).json({ error: "Not found" }); return; }
res.json(conversation);
});
// PATCH /api/conversations/:id
router.patch("/conversations/:id", validate(updateConversationSchema), async (req, res) => {
assertBoard(req);
const conversation = await svc.updateConversation(req.params.id as string, req.body);
res.json(conversation);
});
// DELETE /api/conversations/:id
router.delete("/conversations/:id", async (req, res) => {
assertBoard(req);
await svc.softDeleteConversation(req.params.id as string);
res.status(204).end();
});
// POST /api/conversations/:id/archive
router.post("/conversations/:id/archive", async (req, res) => {
assertBoard(req);
const result = await svc.archiveConversation(req.params.id as string);
res.json(result);
});
// POST /api/conversations/:id/unarchive
router.post("/conversations/:id/unarchive", async (req, res) => {
assertBoard(req);
const result = await svc.unarchiveConversation(req.params.id as string);
res.json(result);
});
// POST /api/conversations/:id/pin
router.post("/conversations/:id/pin", async (req, res) => {
assertBoard(req);
const result = await svc.pinConversation(req.params.id as string);
res.json(result);
});
// POST /api/conversations/:id/unpin
router.post("/conversations/:id/unpin", async (req, res) => {
assertBoard(req);
const result = await svc.unpinConversation(req.params.id as string);
res.json(result);
});
// GET /api/conversations/:id/messages
router.get("/conversations/:id/messages", async (req, res) => {
assertBoard(req);
const cursor = req.query.cursor as string | undefined;
const limit = req.query.limit ? Number(req.query.limit) : undefined;
const result = await svc.listMessages(req.params.id as string, { cursor, limit });
res.json(result);
});
// POST /api/conversations/:id/messages
router.post("/conversations/:id/messages", validate(createMessageSchema), async (req, res) => {
assertBoard(req);
const message = await svc.addMessage(req.params.id as string, req.body);
res.status(201).json(message);
});
return router;
}
```
2. Add to `server/src/routes/index.ts`:
```
export { chatRoutes } from "./chat.js";
```
3. In `server/src/app.ts`, add import `import { chatRoutes } from "./routes/chat.js";` near line 27 (after activityRoutes import), and add `api.use(chatRoutes(db));` after line 158 (after `api.use(activityRoutes(db));`).
4. Create `server/src/__tests__/chat-routes.test.ts` following the exact `activity-routes.test.ts` mock pattern:
- Use `vi.hoisted` to create `mockChatService` with all methods as `vi.fn()`
- `vi.mock("../services/chat.js", () => ({ chatService: () => mockChatService }))`
- `createApp()` function that sets up express with JSON parsing, actor middleware (type: "board", companyIds: ["company-1"]), mounts `chatRoutes({} as any)` under `/api`, and adds `errorHandler`
- Test all behaviors listed in `<behavior>` block
- Also mock `@paperclipai/shared` validators if needed, or let them pass through (they are pure Zod schemas that work without mocking)
<success_criteria>
- Two new DB tables (chat_conversations, chat_messages) with correct columns, indexes, and cascade FK
- Shared types and Zod validators for all create/update operations
- Service layer with full CRUD + auto-title on first message + updatedAt bump
- REST API with 11 endpoints mounted in app.ts
- All automated tests green </success_criteria>