makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(10): create phase plan

Browse Source
This commit is contained in:
Jean-Luc Makiola
2026-03-16 21:26:59 +01:00
parent 66d1cf2f55
commit 67044f8f2e
2 changed files with 306 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
.planning/phases/10-schema-foundation-pros-cons-fields/10-01-PLAN.md Normal file
View File

@@ -0,0 +1,302 @@
---
phase: 10-schema-foundation-pros-cons-fields
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/db/schema.ts
- tests/helpers/db.ts
- src/server/services/thread.service.ts
- src/shared/schemas.ts
- src/client/hooks/useCandidates.ts
- src/client/components/CandidateForm.tsx
- src/client/components/CandidateCard.tsx
- src/client/routes/threads/$threadId.tsx
- tests/services/thread.service.test.ts
autonomous: true
requirements: [RANK-03]
must_haves:
truths:
- "User can open a candidate edit form and see pros and cons text fields"
- "User can save pros and cons text; the text persists across page refreshes"
- "CandidateCard shows a visual indicator when a candidate has pros or cons entered"
- "All existing tests pass after the schema migration (no column drift in test helper)"
artifacts:
- path: "src/db/schema.ts"
provides: "pros and cons nullable TEXT columns on threadCandidates"
contains: "pros: text"
- path: "tests/helpers/db.ts"
provides: "Mirrored pros/cons columns in test DB CREATE TABLE"
contains: "pros TEXT"
- path: "src/server/services/thread.service.ts"
provides: "pros/cons in createCandidate, updateCandidate, getThreadWithCandidates"
contains: "pros:"
- path: "src/shared/schemas.ts"
provides: "pros and cons optional string fields in createCandidateSchema"
contains: "pros: z.string"
- path: "src/client/components/CandidateForm.tsx"
provides: "Pros and Cons textarea inputs in candidate form"
contains: "candidate-pros"
- path: "src/client/components/CandidateCard.tsx"
provides: "Visual indicator badge when pros or cons are present"
contains: "pros || cons"
- path: "tests/services/thread.service.test.ts"
provides: "Tests for pros/cons in create, update, and get operations"
contains: "pros"
key_links:
- from: "src/db/schema.ts"
to: "tests/helpers/db.ts"
via: "Manual column mirroring in CREATE TABLE"
pattern: "pros TEXT"
- from: "src/shared/schemas.ts"
to: "src/server/services/thread.service.ts"
via: "Zod-inferred CreateCandidate type used in service"
pattern: "CreateCandidate"
- from: "src/server/services/thread.service.ts"
to: "src/client/hooks/useCandidates.ts"
via: "API JSON response includes pros/cons fields"
pattern: "pros.*string.*null"
- from: "src/client/hooks/useCandidates.ts"
to: "src/client/components/CandidateForm.tsx"
via: "CandidateResponse type drives form pre-fill"
pattern: "candidate\\.pros"
- from: "src/client/routes/threads/$threadId.tsx"
to: "src/client/components/CandidateCard.tsx"
via: "Props threaded from candidate data to card"
pattern: "pros=.*candidate\\.pros"
---
<objective>
Add pros and cons annotation fields to thread candidates, from database through UI.
Purpose: RANK-03 requires users to add pros/cons text per candidate for decision-making. This plan follows the established field-addition ladder: schema -> migration -> test helper -> service -> Zod -> types -> hook -> form -> card indicator.
Output: Two new nullable TEXT columns (pros, cons) on thread_candidates, fully wired through all layers, with service-level tests and a visual indicator on CandidateCard.
</objective>
<execution_context>
@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
@/home/jlmak/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/10-schema-foundation-pros-cons-fields/10-RESEARCH.md
<interfaces>
<!-- Current codebase contracts the executor needs. -->
From src/db/schema.ts (threadCandidates table -- add pros/cons after status):
```typescript
export const threadCandidates = sqliteTable("thread_candidates", {
id: integer("id").primaryKey({ autoIncrement: true }),
threadId: integer("thread_id").notNull().references(() => threads.id, { onDelete: "cascade" }),
name: text("name").notNull(),
weightGrams: real("weight_grams"),
priceCents: integer("price_cents"),
categoryId: integer("category_id").notNull().references(() => categories.id),
notes: text("notes"),
productUrl: text("product_url"),
imageFilename: text("image_filename"),
status: text("status").notNull().default("researching"),
// ADD: pros: text("pros"),
// ADD: cons: text("cons"),
createdAt: integer("created_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().$defaultFn(() => new Date()),
});
```
From src/shared/schemas.ts (createCandidateSchema -- add optional pros/cons):
```typescript
export const createCandidateSchema = z.object({
name: z.string().min(1, "Name is required"),
weightGrams: z.number().nonnegative().optional(),
priceCents: z.number().int().nonnegative().optional(),
categoryId: z.number().int().positive(),
notes: z.string().optional(),
productUrl: z.string().url().optional().or(z.literal("")),
imageFilename: z.string().optional(),
status: candidateStatusSchema.optional(),
});
// updateCandidateSchema = createCandidateSchema.partial() -- inherits automatically
```
From src/server/services/thread.service.ts:
```typescript
// createCandidate: values() object needs pros/cons
// updateCandidate: inline Partial<{...}> type needs pros/cons
// getThreadWithCandidates: explicit .select({}) projection needs pros/cons
```
From src/client/hooks/useCandidates.ts:
```typescript
interface CandidateResponse {
id: number; threadId: number; name: string;
weightGrams: number | null; priceCents: number | null;
categoryId: number; notes: string | null;
productUrl: string | null; imageFilename: string | null;
status: "researching" | "ordered" | "arrived";
createdAt: string; updatedAt: string;
// ADD: pros: string | null;
// ADD: cons: string | null;
}
```
From src/client/components/CandidateCard.tsx:
```typescript
interface CandidateCardProps {
id: number; name: string; weightGrams: number | null;
priceCents: number | null; categoryName: string;
categoryIcon: string; imageFilename: string | null;
productUrl?: string | null; threadId: number;
isActive: boolean;
status: "researching" | "ordered" | "arrived";
onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
// ADD: pros?: string | null;
// ADD: cons?: string | null;
}
```
From src/client/components/CandidateForm.tsx:
```typescript
interface FormData {
name: string; weightGrams: string; priceDollars: string;
categoryId: number; notes: string; productUrl: string;
imageFilename: string | null;
// ADD: pros: string;
// ADD: cons: string;
}
```
</interfaces>
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: Add pros/cons columns through backend + tests</name>
<files>src/db/schema.ts, tests/helpers/db.ts, src/server/services/thread.service.ts, src/shared/schemas.ts, tests/services/thread.service.test.ts</files>
<behavior>
- createCandidate with pros/cons returns them in the response
- createCandidate without pros/cons returns null for both fields
- updateCandidate can set pros and cons on an existing candidate
- updateCandidate can clear pros/cons by setting to empty string (becomes null via service)
- getThreadWithCandidates includes pros and cons on each candidate object
- All existing thread service tests still pass (no column drift)
</behavior>
<action>
1. **Schema** (`src/db/schema.ts`): Add two nullable TEXT columns to `threadCandidates` after `status`:
```typescript
pros: text("pros"),
cons: text("cons"),
```
2. **Migration**: Run `bun run db:generate` to produce the ALTER TABLE migration, then `bun run db:push` to apply.
3. **Test helper** (`tests/helpers/db.ts`): Add `pros TEXT,` and `cons TEXT,` to the `CREATE TABLE thread_candidates` statement, between the `status` line and the `created_at` line. This is CRITICAL -- without it, in-memory test DBs will silently lack the columns.
4. **Service** (`src/server/services/thread.service.ts`):
- `createCandidate`: Add `pros: data.pros ?? null,` and `cons: data.cons ?? null,` to the `.values({})` object.
- `updateCandidate`: Add `pros: string;` and `cons: string;` to the inline `Partial<{...}>` type parameter.
- `getThreadWithCandidates`: Add `pros: threadCandidates.pros,` and `cons: threadCandidates.cons,` to the explicit `.select({})` projection, before the `categoryName` line.
5. **Zod schemas** (`src/shared/schemas.ts`): Add to `createCandidateSchema`:
```typescript
pros: z.string().optional(),
cons: z.string().optional(),
```
`updateCandidateSchema` inherits via `.partial()` -- no changes needed there.
6. **Tests** (`tests/services/thread.service.test.ts`): Add three test cases:
- In `describe("createCandidate")`: "stores and returns pros and cons" -- create a candidate with `pros: "Lightweight\nGood reviews"` and `cons: "Expensive"`, assert both fields are returned correctly.
- In `describe("updateCandidate")`: "can set and clear pros and cons" -- create a candidate, update with pros/cons values, assert they are set, then update with empty strings, assert they are cleared (returned as empty string or null from DB).
- In `describe("getThreadWithCandidates")`: "includes pros and cons on each candidate" -- create a candidate with pros/cons, fetch via getThreadWithCandidates, assert `candidate.pros` and `candidate.cons` match.
</action>
<verify>
<automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test tests/services/thread.service.test.ts</automated>
</verify>
<done>
- pros and cons columns exist in schema.ts and test helper
- Drizzle migration generated and applied
- createCandidate, updateCandidate, getThreadWithCandidates all handle pros/cons
- Zod schemas accept optional pros/cons strings
- All existing + new thread service tests pass
</done>
</task>
<task type="auto">
<name>Task 2: Wire pros/cons through client hooks, form, and card indicator</name>
<files>src/client/hooks/useCandidates.ts, src/client/components/CandidateForm.tsx, src/client/components/CandidateCard.tsx, src/client/routes/threads/$threadId.tsx</files>
<action>
1. **Hook** (`src/client/hooks/useCandidates.ts`): Add to `CandidateResponse` interface:
```typescript
pros: string | null;
cons: string | null;
```
2. **CandidateForm** (`src/client/components/CandidateForm.tsx`):
- Add `pros: string;` and `cons: string;` to `FormData` interface.
- Add `pros: "",` and `cons: "",` to `INITIAL_FORM`.
- In the `useEffect` pre-fill block, add: `pros: candidate.pros ?? "",` and `cons: candidate.cons ?? "",`.
- In `handleSubmit` payload, add: `pros: form.pros.trim() || undefined,` and `cons: form.cons.trim() || undefined,`.
- Add two textarea elements in the form, AFTER the Notes textarea and BEFORE the Product Link input. Each should follow the exact same pattern as the Notes textarea:
- **Pros**: label "Pros", id `candidate-pros`, placeholder "One pro per line...", rows={3}
- **Cons**: label "Cons", id `candidate-cons`, placeholder "One con per line...", rows={3}
- Use identical Tailwind classes as the existing Notes textarea.
3. **CandidateCard** (`src/client/components/CandidateCard.tsx`):
- Add `pros?: string | null;` and `cons?: string | null;` to `CandidateCardProps` interface.
- Destructure `pros` and `cons` in the component function parameters.
- Add a visual indicator badge in the `flex flex-wrap gap-1.5` div, after the StatusBadge. When `(pros || cons)` is truthy, render:
```tsx
{(pros || cons) && (
<span className="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-purple-50 text-purple-700">
+/- Notes
</span>
)}
```
4. **Thread detail route** (`src/client/routes/threads/$threadId.tsx`): Pass `pros` and `cons` props to the `<CandidateCard>` component in the candidates map:
```tsx
pros={candidate.pros}
cons={candidate.cons}
```
5. Run `bun run lint` to verify Biome compliance (tabs, double quotes, organized imports).
</action>
<verify>
<automated>cd /home/jlmak/Projects/jlmak/GearBox && bun test && bun run lint</automated>
</verify>
<done>
- CandidateResponse includes pros/cons fields
- CandidateForm shows Pros and Cons textareas, pre-fills in edit mode, sends in payload
- CandidateCard shows purple "+/- Notes" badge when pros or cons text exists
- Thread detail page threads pros/cons props to CandidateCard
- Full test suite passes, lint passes
</done>
</task>
</tasks>
<verification>
1. `bun test` -- full suite green (existing + new tests)
2. `bun run lint` -- no Biome violations
3. Manual: create a thread, add a candidate with pros and cons text, verify:
- Pros/cons fields appear in the edit form
- Saved text persists after page refresh
- CandidateCard shows the "+/- Notes" indicator badge
- A candidate without pros/cons does NOT show the badge
</verification>
<success_criteria>
- RANK-03 fully implemented: pros/cons fields on candidates, editable via form, persisted, with visual indicator
- Zero test regressions
- No column drift between schema.ts and test helper
</success_criteria>
<output>
After completion, create `.planning/phases/10-schema-foundation-pros-cons-fields/10-01-SUMMARY.md`
</output>