Codewalkers/.planning/phases/07-file-system-ui/07-02-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
07-file-system-ui	02	execute	2	07-01	src/filesync/writer.ts src/filesync/writer.test.ts src/filesync/index.ts	true

Implement message file writer for DB→FS sync direction (FSUI-02).

Purpose: Agent messages automatically appear as files in designated directory. Output: MessageFileWriter class that creates/updates/deletes message files from DB state.

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

Depends on 07-01:

@src/filesync/types.ts @src/events/types.ts

Message schema for reference:

@src/db/schema.ts @src/db/repositories/message-repository.ts

Task 1: Create MessageFileWriter class src/filesync/writer.ts Create MessageFileWriter class that handles DB→FS direction:

1. Constructor takes:

   • messagesDir: string (e.g., '.cw/messages')
   • eventBus?: EventBus (optional for events)

2. Methods:

   • writeMessage(message: Message, agentName: string): Promise

     • Create/update file at {messagesDir}/{agentName}-{messageId}.md
     • Format: YAML frontmatter + markdown body (see format below)
     • Emit filesync:synced event on success
     • Emit filesync:error event on failure

   • deleteMessage(messageId: string, agentName: string): Promise

     • Delete file if exists
     • No error if file doesn't exist (idempotent)

   • writeAllMessages(messages: Array<{ message: Message; agentName: string }>): Promise<SyncResult[]>

     • Batch write for initial sync

   • ensureDirectory(): Promise

     • Create messagesDir if not exists

3. File format (YAML frontmatter + markdown):

---
messageId: abc123
agentName: gastown
type: question
requiresResponse: true
status: pending
parentMessageId: null
createdAt: 2026-01-30T12:00:00.000Z
updatedAt: 2026-01-30T12:00:00.000Z
---

What color should the button be?

4. Use js-yaml for YAML serialization (add to dependencies if needed). Use gray-matter for frontmatter parsing (already common pattern). If neither available, use simple string template (YAML is simple enough).

5. File naming: {agentName}-{messageId}.md

   • Human-readable agent name for easy identification
   • messageId for uniqueness tsc --noEmit passes MessageFileWriter class created with write/delete operations

Task 2: Add unit tests src/filesync/writer.test.ts Create comprehensive tests for MessageFileWriter:

1. Setup:

   • Use tmp directory for test isolation
   • Create mock EventBus for event verification
   • Create test message objects

2. Test cases:

   • writeMessage creates file with correct format
   • writeMessage updates existing file
   • writeMessage emits filesync:synced event
   • deleteMessage removes file
   • deleteMessage is idempotent (no error if file missing)
   • writeAllMessages batch creates files
   • ensureDirectory creates directory if missing
   • Error cases emit filesync:error event

3. Verify file content:

   • Parse written file, check frontmatter fields match
   • Check markdown body matches content

Use vitest patterns from existing tests (e.g., src/coordination/manager.test.ts). npm test -- src/filesync/writer.test.ts passes Writer tests pass, verify file format correctness

Task 3: Update module exports src/filesync/index.ts Add MessageFileWriter to exports:

export * from './types.js';
export * from './writer.js';

import { MessageFileWriter } from './src/filesync/index.js' works Writer exported from module Before declaring plan complete: - [ ] `npm run build` succeeds without errors - [ ] `npm test -- src/filesync/writer.test.ts` passes - [ ] File format is correct YAML frontmatter + markdown - [ ] Events emitted correctly

<success_criteria>

• All tasks completed
• All verification checks pass
• No errors or warnings introduced
• FSUI-02 requirement satisfied (agent messages appear as files) </success_criteria>

After completion, create `.planning/phases/07-file-system-ui/07-02-SUMMARY.md`